pull-request skill: pre-create gate must verify non-empty '## Related' section

[kyle-sexton]

Context

The pr-issue-linkage gate requires BOTH a closing keyword (or explicit no-issue opt-out) AND a non-empty ## Related section. The source-control:pull-request skill's pre-create gate (create.md §2.4.2) greps only for the closing keyword — it never verifies ## Related — so agent-composed bespoke PR bodies pass the skill-side check and fail at CI. This is the top confirmed break behind the fleet's most-reported CI failure (5 of 6 recent claude-code-plugins linkage failures were the ## Related error; PR #934 shows the fail-at-open → edit-body → pass-81s-later churn cycle). Affects both cached plugin versions (0.15.8, 0.16.2) — logic gap, not staleness.

Proposed work

• Extend the pre-create gate in the pull-request skill's create flow to verify a non-empty ## Related section (mirroring the gate's actual validation, ideally sourced from/tested against the ci-workflows pr-issue-linkage logic rather than a hand-copied regex)
• Ensure the body-assembly path always scaffolds ## Related (with - N/A default) for bespoke bodies, not only the template heredoc path

Acceptance criteria

• A PR body missing/empty ## Related is caught before gh pr create, with a fix hint
• The skill-side check provably matches the gate's validation (test or shared source), so they cannot drift

References

• medley docs/topics/cicd-fleet-audit/REPORT.md — issue-linkage root cause (break 1 of 3)
• Evidence: .work/cicd-fleet-audit/data/issue-linkage-chain.md in medley
• ci-workflows#153 (enforcement-scope decision for remaining body sections — coordinate)

[kyle-sexton]

Interview decision locked (cicd-fleet-audit follow-up):

Constraint (owner): implementation must not compromise the plugin repo's philosophy — modularity, extensibility, configurability, provider/org agnosticity. Therefore: do NOT hardcode the melodic pr-issue-linkage contract (## Related requirement) into the skill.

Locked shape:

• The skill gains a generic, configurable required-body-sections pre-create check (mechanism only; default = current behavior). Policy arrives via the source-control layered config, not skill source.
• The melodic-specific contract (closing keyword + non-empty ## Related) is expressed as policy data in the consumer config layer.
• Align with Program: PR convention policy-as-data — one policy file, one validator, thin CI runners, plugin mechanism standards#173 (PR convention policy-as-data: one policy file, one validator, thin CI runners, plugin mechanism) — the gate and the skill should ultimately validate from the SAME policy data, which kills this drift class at the root. Coordinate there before inventing a second policy format.
• Conformance fixtures: plugin tests exercise the mechanism generically; melodic policy-vs-gate conformance lives with the policy file, not in this repo.

[kyle-sexton]

Locked decisions (interview + research, 2026-07-22)

1. Config seam: new key in .claude/source-control.md (3-layer resolution, per-key override — the format is current and stable; fleet adoption is greenfield). Documented under a concern-named docs/conventions/ directory per the commit-convention prior art (same file, two consumers: source-control drafting reads all layers; enforcement reads team-tracked layer).
2. Key shape (V1): flat list of required section headings. Richer per-section schema (required/optional, min-content, placeholder rejection, CONDITIONAL sections — e.g. GitLab's screenshots-only-for-UI-changes, kubernetes' NONE-sentinel release-note block) is DEFERRED, trigger = standards#173's first implementation PR. The conditional-sections limitation is a known, recorded gap of the flat list.
3. Portable default (no config present): Summary + Test plan ONLY. Research verdict (GitHub docs/blog, Google eng-practices CL descriptions, GitLab's dogfooded Default.md, 8 OSS templates + anti-heavy-template falsification): what/why + test evidence is the near-universal core and assumes nothing about the consuming repo; a Related/linked-issue section presumes an issue-tracking convention — org-specific, so it moves from hardcoded template to melodic config data. Plugin stays fully agnostic (philosophy: only non-conflicting good-practice may be hardcoded).
4. Melodic org policy (config data, not plugin content): Summary, Test plan, Related + the closing-keyword line — unchanged from current practice, now declared per-repo via the team layer instead of baked into the plugin.
5. Gate must teach: the pre-create body gate (and any future CI consumer) fails naming the exact missing section AND pointing at the policy source (the config file/key), so an actor who never saw the convention learns where it lives — pit-of-success requirement.
6. build: Bump the github-actions group across 1 directory with 11 updates #173 convergence: V1 resolves only its own config; the materialized-policy relationship is deferred with the same build: Bump the github-actions group across 1 directory with 11 updates #173 trigger. ## Related enforcement stays fleet-wide (USER-RESERVED question resolved; conventions/process/issue-tracker.md to be reconciled to match — tracked in standards, not here).

Owner constraint reaffirmed: no melodic-specific behavior ships in the plugin; melodic policy exists only as configuration data.