Commit-issue traceability: standardise Refs #NN and defuse auto-close keywords

[PBNZ]

Retrospective finding — refs #10.

Context

Two related findings:

1. Traceability is near zero. Across roughly 260 commits in eight single-maintainer repos,
   effectively none reference an issue — the only refs present were bot/external-PR artifacts.
   One repo demonstrably ran issue-driven work (its changelog cites issue numbers) yet not one
   commit subject carries them: the traceability lives in changelog prose where no tooling can
   follow it. The standard mandates Conventional Commits but says nothing about issue linkage.
2. Auto-close keywords are a footgun where a human gate exists. In a multi-person,
   board-driven project, the documented Closes #NN convention auto-closed seven issues at PR
   merge — silently skipping the project's human verification step, which by design happens
   after landing on the main branch. The local fix: reference issues as plain Refs #NN,
   humans close after verifying, and a CI job rejects any PR whose body or commit messages
   contain a closing keyword followed by an issue reference.

Proposal

1. Convention: when a repo uses an issue tracker, commits/PRs reference the driving issue as
   Refs #NN (subject or footer). Repos without a tracker are exempt — but must not half-adopt
   (issue numbers in changelog prose only is the worst of both).
2. Closing-keyword guidance: closing keywords are appropriate only where merge genuinely
   equals done (solo repo, no post-merge verification). Where any human verify step follows the
   merge, the standard prescribes Refs + manual close.
3. Ship the guard: provide the closing-keyword-rejecting CI job as a reusable snippet in the
   standard (it exists and is field-tested), plus a PR-template line prompting Refs #NN.

Tasks

• Add the traceability convention to the commit-conventions reference.
• Add the closing-keyword decision rule ("merge == done? then and only then").
• Publish the CI snippet + PR-template line; wire into scaffold for board-driven repos.

Acceptance criteria

• A repo adopting the standard can answer "which issue drove this commit" from git log alone.
• The auto-close failure mode is documented with its guard available as copy-paste.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Triage: accepted.

Landed on PR #18 (commit e577345): commit-conventions.md gains Issue traceability — Refs #NN in subject/footer when a tracker exists, the no-half-adoption rule, and the decision rule for closing keywords (only where merge genuinely equals done; any post-merge verify gate → Refs + manual close). The field-tested auto-close CI guard is published as a copy-paste snippet, and both PR templates (this repo's + the scaffolded Public-tier one) now prompt for the ref. This PR itself dogfoods the convention — one Refs #NN commit per issue, no closing keywords.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Verified on main (f7ab31c): Issue traceability in commit-conventions.md, Refs prompts in both PR templates, and the no-auto-close guard adopted in this repo's own CI — it ran green on PR #18, which itself carried one Refs #NN commit per issue and was closed by humans, not keywords. Closing on @PBNZ's instruction.

— 🤖 Claude, on behalf of @PBNZ