source-control/repo: PRs fail pr-issue-linkage (missing `## Related`) — no template scaffolds the required sections

[kyle-sexton]

Lane: work (issue-execution loop, orchestrator dispatching per-issue subagents)
Category: operational

Triggering example

During a /work-items:work loop, subagents created PRs #457 and #458 (and #460) via gh pr create with hand-written bodies containing a Closes #N keyword. All three FAILED the required pr-issue-linkage check with:

##[error]Missing a "## Related" section. List related PRs, ADRs, or decision-log entries this PR does not close.

The pr-issue-linkage reusable workflow (melodic-software/ci-workflows) requires BOTH a native closing keyword AND a non-empty ## Related section. There is no .github/pull_request_template.md in the repo, so nothing scaffolds ## Related. Every author — human or agent — discovers the requirement only after a red CI run, then edits the body and burns a second CI cycle.

Observed vs expected

• Observed: No PR template. PR bodies start non-compliant; the ## Related contract is enforced only reactively by CI. Both ad-hoc gh pr create and the /source-control:pull-request path omitted it.
• Expected: A repo pull_request_template.md (and/or the /source-control:pull-request skill's reference/create.md) scaffolds the ## Related section + closing-keyword line so PRs are linkage-compliant on first push.

Suggested fix

Add .github/pull_request_template.md with a ## Related section + a closing-keyword placeholder mirroring the pr-issue-linkage contract, and have /source-control:pull-request emit that skeleton. The single source of truth stays the ci-workflows validator; the template/skill just scaffold to match it.

[kyle-sexton]

This was generated by AI during triage.

Triage → T2 planning complete · confidence: high. Verified against the actual SSOT validator (ci-workflows → .github/workflows/pr-issue-linkage.yml), the plugin source (v0.9.0), and GitHub's PR-template docs. Split fix preserves plugin agnosticism. Labeling status: ready.

Scaffold ## Related + closing keyword so PRs pass pr-issue-linkage on first push

Verified root cause

The validator requires exactly two things (## Summary/## Test plan are not checked):

1. A level-2 ## Related heading whose body, after HTML comments are stripped, is non-empty (extractSection(body, /^##\s+related$/i)).
2. A native closing keyword /\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s*(?:owner\/repo)?#\d+\b/i OR a no (?:linked|related) issue marker.

The validator strips <!-- … --> before every check — so a ## Related whose only content is an HTML comment is treated as empty and fails. Default content must be visible text.

The plugin skill does NOT mechanically read a repo PR template. It carries only prose intent (skills/pull-request/SKILL.md "Consumer conventions…"; create.md §2.4.1 "When the consuming project ships a PR template, mirror its section shape") — but the actual §2.4.1 body-assembly emits a fixed heredoc (## Summary/## Test plan + attribution) and prepends Closes #N. No script reads .github/pull_request_template.md. It does not hardcode ## Related, so today's fallback is already agnostic.

Behavioral contract

1. A claude-code-plugins PR is linkage-compliant on first push (no red-CI-then-edit cycle) — both the web-UI/bare-gh path and the /source-control:pull-request path.
2. The plugin stays repo-agnostic — never hardcodes a melodic-specific ## Related (the source-control: PR-body "Generated with Claude Code" attribution is unconditional — no trailer_policy-equivalent seam #439 defect class). It emits the consuming repo's template, or its neutral default when none ships.
3. The ci-workflows validator remains SSOT; template file + skill only scaffold to match.

Why the fix must be in TWO places (linchpin)

create.md §2.4.1 already notes gh pr create --body fully overrides any repo .github/PULL_REQUEST_TEMPLATE.md (cli/cli#10751), and the skill always passes --body. So:

• A repo template file alone reaches web-UI + bare-gh authors, but can never reach the skill path (--body overrides it).
• Only a skill change makes the skill path honor the template. Prose already told it to and it still failed → a doc-note-only change is a band-aid. Neither half alone closes source-control/repo: PRs fail pr-issue-linkage (missing ## Related) — no template scaffolds the required sections #462.

Fix 1 — repo-side (melodic-specific, correct to be so): add .github/pull_request_template.md to claude-code-plugins

<!--
Fill "Closes #<n>" with the issue this PR closes (Closes/Fixes/Resolves + #number).
If it closes nothing, replace that line with: No linked issue
-->
Closes #<issue>

## Summary

<!-- What changed and why. -->

## Test plan

- <!-- How this was verified. -->

## Related

<!-- Related PRs, ADRs, or decision-log entries this PR does NOT close. Keep "- None" if there are none. -->
- None

• Visible - None default (a comment-only default would strip to empty and fail). Truthful, not a rubber-stamp — ## Related is for links the PR does not close, so a simple PR legitimately has none.
• Placeholder Closes #<issue> doesn't match #\d+, so it never auto-closes and keeps the gate red until a real number (or No linked issue) is filled.

Fix 2 — plugin-side (agnostic): make create.md §2.4.1 mechanically honor a repo template

Replace the soft "mirror its section shape" prose with a concrete detection step:

1. Detect a single-file repo template (case-insensitive, first match wins): .github/pull_request_template.md, root pull_request_template.md, docs/pull_request_template.md.
2. If found: use the file contents verbatim as the PR-body base (instead of the fixed heredoc), then apply the existing closing-keyword injection — guard duplication by reusing the §2.4.2 keyword regex: prepend the resolved Closes #N only if the base lacks a valid keyword. The skill does not parse/rename/fill any repo-specific section — the repo's template owns those.
3. If not found: fall back to the current fixed heredoc — unchanged for external consumers.
4. Multiple-template directory (.github/PULL_REQUEST_TEMPLATE/): can't know which to pick → fall back to the default heredoc (documented fallback, not an open decision).

Acceptance criteria

• Web-UI/bare-gh PR renders ## Summary/## Test plan/## Related (default - None) + a Closes prompt; passes pr-issue-linkage on first push once the keyword is filled.
• /source-control:pull-request in claude-code-plugins detects the template, emits it as the body base, prepends resolved Closes #N → both gates green on the first CI run.
• In a repo with no template, /source-control:pull-request output is unchanged from today.
• Plugin source contains no literal ## Related string (grep verifies) — agnosticism preserved.
• The repo template's ## Related default survives the HTML-comment strip as non-empty (- None, not comment-only).

Notes

• The skill already carries prose intent to honor a repo template — Fix 2 hardens that soft instruction into a mechanical step (why the reporter says it "omitted it"). Small, well-anchored change, not a redesign.
• The linkage validator's source already widens its no-issue marker to accept this plugin's No related issue: opt-out — the cross-repo relationship is intentional and coordinated; Fix 2 aligns with it.
• ## Summary/## Test plan aren't gate-required (only ## Related + keyword are) — included for parity with the skill's body shape; droppable if the team wants a minimal template.
• Minor implementation check: use case-insensitive template-filename detection (GitHub's lookup is case-insensitive).