docs(contributing): the branch-naming rule is enforced by nothing and unqualified

[kyle-sexton]

Summary

CONTRIBUTING.md Workflow step 1 states an unqualified requirement:

1. Branch from the default branch using <type>/<description> (for example, feat/add-widget).

Nothing enforces it. There is no branch-name rule, regex, or gate anywhere in this repository, and branch protection in the org ruleset does not constrain head-branch names.

#93 and #95 just made this inconsistent with its own neighbours. Step 4 now carefully qualifies the PR-title requirement — "Where the repository enforces this, a pr-title check reports on your pull request and must pass before merge" — and step 5 describes the merge gate that is actually enforced. Step 1 sits beside them making a bare imperative claim with no enforcement and no qualifier, so a reader has no way to tell it is advisory.

This matters more than a normal doc nit because CONTRIBUTING.md is an org-wide inherited default: the unqualified rule is read by every human contributor and every agent working in any repository that has not overridden it.

Evidence

Found by a blind reconstruction check: a fresh agent barred from reading the policy docs was asked to determine the branch-naming convention from primary sources alone. It returned could not determine, reporting no rule, regex, or gate anywhere in the repo. The only adjacent signal it found was a comment in ci.yml noting that fork branches may collide (e.g. both named patch-1), which argues concurrency should key on PR number rather than branch name — i.e. evidence that branch names are explicitly not controlled.

The decision

Two coherent options; this needs a call rather than a default:

1. Enforce it. Add a branch-name gate. That work belongs in ci-workflows (the check) and possibly github-iac (wiring it into the ruleset), not in this repository.
2. Qualify it. Reword step 1 to match the honesty of steps 4 and 5 — state it as a convention rather than a requirement.

Option 2 is the cheap one and is consistent with the direction #93 and #95 just set. Option 1 is the durable one if the convention is actually wanted org-wide.

Scope

Small, if option 2. Cross-repo, if option 1.

Provenance

Surfaced by a /docs-hygiene:audit-derivability sweep of this repo's tracked markdown. The sweep's other two routed findings were re-checked against main and dropped as superseded: the README config-list trim was reversed by #80 and #83, and the CONTRIBUTING gate-restatement trim was reversed by #93 and #95. This is the only one that survived.

[kyle-sexton]

Claiming for gate-audit re-check (role-label legitimacy panel).

[kyle-sexton]

This was generated by AI during triage (gate-audit re-check, instance KYLE-triage-20260823-1424).

Gate-audit panel result

Two independent fresh-context reviewers plus my own independent read were asked to classify this issue cold (issue content only, no prior rationale fed in):

• codex:rescue (fresh context): VERDICT: NEEDS-HUMAN — "this needs a call rather than a default" is a genuine policy/priority decision with no single objectively correct answer; option 1 also carries cross-repo scope (ci-workflows/github-iac).
• My own independent read: NEEDS-HUMAN — same reasoning; a wording tweak vs. an org-wide enforcement gate is a scope/priority call, not a mechanical fix.
• (A third fresh-context general-purpose reviewer was also dispatched; not required to reach 2-of-3-or-better and not waited on further.)

2-of-3-or-better agree: the needs-human gate here is legitimate. Leaving it gated.

Decision-ready summary

RECOMMENDED — Option 2: reword CONTRIBUTING.md Workflow step 1 to state the branch-naming pattern as a convention rather than an enforced requirement, matching the qualified phrasing already used in steps 4 and 5 (post-#93/#95). Small, single-repo, immediately consistent, fully reversible.

ALTERNATIVE — Option 1: build an actual branch-name enforcement gate (regex/rule) — the check belongs in ci-workflows, wiring into the org ruleset belongs in github-iac. Durable if the convention is genuinely wanted org-wide, but cross-repo scope and requires deciding whether to bind branch names for real (interacts with the ci.yml note that fork branches may collide on name, which favors keying on PR number rather than branch name).

A human can clear this by picking one of the two options above; no further investigation is needed first.

[kyle-sexton]

Gate-audit complete; releasing claim. Gate left in place (see decision-ready summary above).

[kyle-sexton]

This was generated by AI in a documentation lane (dotgithub).

Resolved: option 2. Merged as 8c9891974a616e305dd4c12f9345de4ac5691289 (PR #104, squashed to main 2026-08-27T10:16:12Z). Confirmed on main, CONTRIBUTING.md Workflow step 1:

Branch from the default branch, naming it <type>/<short-description> (for example, feat/add-widget) per the org's branch-naming convention. A repository may gate the pattern locally, but no check enforces it by default, so treat it as a convention rather than a requirement.

A correction to this issue's framing, which changed how option 2 was executed. The issue says "Nothing enforces it. There is no branch-name rule, regex, or gate anywhere in this repository." The gate half is true and was re-confirmed. The rule half is not: the org has a canonical branch-naming convention, in melodic-software/standards conventions/engineering/naming.md "Branch names: type prefix, then a behavior-naming slug". It defines the grammar, pins the type vocabulary to the eleven Conventional Commits types, and carves out agent/bot prefixes (claude/, codex/, cursor/, copilot/, dependabot/) that must be left as generated.

That matters because it is this issue's root cause. The evidence here is a derivability failure — a fresh agent reading primary sources returned could not determine the branch-naming convention. It could not determine it because step 1 restated a convention without ever naming it. A pure qualifier would have left that standing: step 1 would still paraphrase an unnamed source. So the fix qualifies and cites, and aligns the placeholder to the canonical <type>/<short-description> — citing a source while restating it inaccurately would manufacture exactly the drift this issue exists to remove.

Why option 2 and not option 1. Standards has already classified this rule, and its classification argues against a new gate. naming.md calls the type and tool prefixes "a fixed, exact-match set: deterministic... so a repo may gate the pattern with a commit hook" — permissive, not required. It then rules on the value directly: "Branch name is cosmetic once a PR merges through a squash workflow: the PR title becomes the default-branch history, which is why enforcing the Conventional Commits vocabulary at PR-title time... matters more for history hygiene than the branch name does; the branch grammar exists to keep local development and in-flight PRs legible in the meantime."

This repository already runs that higher-value gate (pr-title.yml, documented in step 4). Option 1 would add a second gate over the same vocabulary at the point standards calls cosmetic. enforceability-tiers.md supplies the tiebreaker: tier classification answers whether a rule can be mechanized, but "whether a candidate is worth mechanizing... is a separate decision, and the default answer is 'not yet'." Nothing here offered evidence of the convention being violated, and ci.yml's header comment records that fork branches may collide on name — head-branch names are already treated as uncontrolled.

Option 1 stays open on its merits; standards explicitly leaves the door open for any repository that wants it, and a later gate would simply tighten the new sentence.

Note on the qualifier's wording. An earlier draft said flatly "no check constrains branch names." That is wrong to assert in a file every non-overriding repository inherits, since standards contemplates a repository gating the pattern locally. The shipped wording scopes the claim to the default and leaves room for a repository that gates.

How it was verified. A fresh-context verifier (opus, no authoring context) judged the final state and failed it on the first pass, catching a false claim in the PR body: it had asserted that standards contains no branch-naming convention doc. It does — that is how naming.md was found. The body was corrected, the argument rebuilt on what that file actually says, the prose re-hedged, the placeholder aligned, and the branch force-pushed; CI re-ran green and re-verification returned PASS.

The passing verdict confirmed: every naming.md quotation verbatim and not selectively cropped (the counter-weight clause about in-flight legibility is retained, so the sentence cutting against the argument is shown); the enforceability-tiers.md quotation verbatim; the link anchor resolving against the live heading, with lychee.toml's include_fragments = "full" and standards being public, so it resolves for every reader of this org-wide default; the placeholder matching naming.md character-for-character; and the surviving absence claim re-checked across this repository, ci-workflows (all 38 workflows plus the .github/actions/ tree — the only head_ref uses are a checkout ref, a dependabot/nuget/ trigger condition, and refs/heads/main run guards) and standards' lefthook.yml. markdownlint-cli2@0.23.2 clean; all 14 CI checks pass; scope one file, one line. It also ruled explicitly that the added citation and placeholder alignment serve this issue rather than exceed it. Verdict: PASS.

One residual nit, deliberately not fixed: the retained example feat/add-widget is a two-word slug where the now-cited naming.md suggests "3-5 words is a reasonable aim". That is an aim rather than a rule, and changing it would have widened the diff.