Skip to content

Name the collation for the reference-definition sort order - #586

Merged
ptr727 merged 1 commit into
developfrom
feature/583-reference-definition-collation
Aug 6, 2026
Merged

Name the collation for the reference-definition sort order#586
ptr727 merged 1 commit into
developfrom
feature/583-reference-definition-collation

Conversation

@ptr727

@ptr727 ptr727 commented Aug 6, 2026

Copy link
Copy Markdown
Owner

"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.

"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>
Copilot AI lite review requested due to automatic review settings August 6, 2026 13:47

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 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.md that 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.md for 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
ptr727 merged commit e848a4d into develop Aug 6, 2026
7 checks passed
@ptr727
ptr727 deleted the feature/583-reference-definition-collation branch August 6, 2026 13:53
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.
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