Name the collation for the reference-definition sort order - #586
Merged
Conversation
"Alphabetized by reference name" is ambiguous wherever one label is a prefix of another, and the two readings disagree on that pair alone. Sorting the bare label puts `[governance]` first, while sorting the whole definition line puts `[governance-branching-model]` first, because `-` (0x2D) precedes `]` (0x5D). A block ordered either way is internally consistent, so a reviewer reads the other one as a defect and asks for a re-sort on every pull request that touches a definition block. ## The reading is already in the tree Every reference-definition group this repository carries, twelve of them across ten files, sorts by the bare label. `[governance]` above `[governance-branching-model]`, `[repo-config]` above `[repo-config-settings]`, `[vscode-tasks]` above `[vscode-tasks-python]`. None sorts by the line. The rule's own wording says "by reference name", so the bare label is both what the sentence says and what the corpus does, and the line reading would mean re-sorting `README.md`, `AUDIT.md`, `CODESTYLE.md`, `STANDUP.md`, `TODO.md`, and five more against a rule that never asked for it. `GOVERNANCE.md` now names the key rather than leaving it inferred: the text inside the brackets, never the whole line, so a shorter name sorts above one it prefixes. It also records the trap, which is that a plain `sort -c` over the block passes on the inverted order, since that command compares the line. A block can therefore be mechanically "sorted" and still be wrong, which is how a consistent block reaches review. `spec/readme-structure.md` restates the same rule for a repository that reads the spec without the governance file, so it carries the key too. Leaving it at "alphabetized within each group" would hand the same guess to exactly the reader who has nothing else to check against. ## Two blocks were unsorted under either reading `WORKFLOW.md` and `docs/repo-config-carry.md` each carry a `<!-- Repo -->` group ordered by neither collation. Both are fixed here, so the canonical satisfies the rule it states. ## Verification `prose_lint.py --diff`, `repo_gate.py`, and `markdownlint-cli2` are clean over the change, and a scan of every definition group in the tree reports zero violating the stated order. `GOVERNANCE.md` is verbatim-carried, so a fleet re-vendor is owed. Fixes #583. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR removes ambiguity in how reference-link definition blocks are alphabetized by explicitly naming the collation key (the reference name inside [], not the full definition line), and it brings a couple of existing definition groups into compliance with that clarified rule.
Changes:
- Clarify in
GOVERNANCE.mdthat reference-link definitions are sorted by the reference name alone (so prefix pairs sort with the shorter name first). - Mirror the same clarification in
spec/readme-structure.mdfor spec readers who may not consult governance text. - Fix two
<!-- Repo -->definition blocks (WORKFLOW.md,docs/repo-config-carry.md) to match the stated ordering.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| WORKFLOW.md | Reorders <!-- Repo --> reference definitions to match the clarified reference-name collation. |
| spec/readme-structure.md | Specifies the exact sort key for reference-link definition blocks (reference name only). |
| GOVERNANCE.md | Defines the collation rule explicitly and documents why line-sorting is a trap for prefix pairs. |
| docs/repo-config-carry.md | Reorders <!-- Repo --> reference definitions into correct reference-name sort order. |
ptr727
added a commit
that referenced
this pull request
Aug 6, 2026
#586 named the collation for reference-definition sort order as the text inside the brackets, and #588 then inserted into two blocks without applying it. Found by Copilot on the promotion pull request #589, which is blocked on both threads. ## The two blocks - `CODESTYLE.md` appended the two `vscode-tasks` links after `ruff-link` when it repointed them into hub-only `catalog/`, which stranded `uv-link` below them. `uv-link` belongs between `ruff-link` and `vscode-tasks-link`. - `docs/repo-config-carry.md` put `governance-hub-hosted-tooling` at the head of a `<!-- Repo -->` group #586 had itself just sorted, above `governance-documentation-style` and `governance-git-and-commit-rules`. Both are pure reorderings. No link target, anchor, or reference name changes, so no rendered output changes. ## Why a mechanical check did not catch it This is exactly the trap #586 recorded when it named the key. A plain `sort -c` over either block compares the whole line rather than the bracketed label, and both blocks pass that reading, so a "sorted" block reaches review looking consistent. Nothing in `repo_gate.py` or `prose_lint.py` asserts the order today, which is why the reviewer is the only surface that flagged it. ## Verification A sweep over every reference-definition group in every markdown file in the tree, keyed on the bare label, reports these two groups and no others before the change, and zero after it. `scripts/prose_lint.py --diff origin/develop` and `scripts/repo_gate.py` are both clean. Refs #583 Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 6, 2026
…, and the operational pull-request trigger (#589) Promotes the five commits develop carried since #582: #584 (a Copilot refusal is not coverage), #586 (the reference-definition collation), #587 (CI on a pull request into an operational develop), #588 (hub-hosted tooling, de-vendoring configure.sh), and #590 (the two definition blocks #588 pushed out of order). Merge commit, no squash, develop not deleted. git merge-tree reported no conflict and wrote a tree byte-identical to origin/develop. GOVERNANCE.md is verbatim-carried and three of these commits change it, so a fleet re-vendor is owed, including an entirely new carried section. #588 also turns every downstream repo-config/configure.sh copy into a deletion rather than a convergence, and #587 leaves a one-line trigger change owed by four operational repos.
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.
"Alphabetized by reference name" is ambiguous wherever one label is a prefix of another, and the two readings disagree on that pair alone. Sorting the bare label puts
[governance]first, while sorting the whole definition line puts[governance-branching-model]first, because-(0x2D) precedes](0x5D). A block ordered either way is internally consistent, so a reviewer reads the other one as a defect and asks for a re-sort on every pull request that touches a definition block.The reading is already in the tree
Every reference-definition group this repository carries, twelve of them across ten files, sorts by the bare label.
[governance]above[governance-branching-model],[repo-config]above[repo-config-settings],[vscode-tasks]above[vscode-tasks-python]. None sorts by the line. The rule's own wording says "by reference name", so the bare label is both what the sentence says and what the corpus does, and the line reading would mean re-sortingREADME.md,AUDIT.md,CODESTYLE.md,STANDUP.md,TODO.md, and five more against a rule that never asked for it.GOVERNANCE.mdnow names the key rather than leaving it inferred: the text inside the brackets, never the whole line, so a shorter name sorts above one it prefixes. It also records the trap, which is that a plainsort -cover the block passes on the inverted order, since that command compares the line. A block can therefore be mechanically "sorted" and still be wrong, which is how a consistent block reaches review.spec/readme-structure.mdrestates the same rule for a repository that reads the spec without the governance file, so it carries the key too. Leaving it at "alphabetized within each group" would hand the same guess to exactly the reader who has nothing else to check against.Two blocks were unsorted under either reading
WORKFLOW.mdanddocs/repo-config-carry.mdeach carry a<!-- Repo -->group ordered by neither collation. Both are fixed here, so the canonical satisfies the rule it states.Verification
prose_lint.py --diff,repo_gate.py, andmarkdownlint-cli2are clean over the change, and a scan of every definition group in the tree reports zero violating the stated order.GOVERNANCE.mdis verbatim-carried, so a fleet re-vendor is owed.Fixes #583.