fix(source-control): scaffold ## Related section in pull-request create flow (#487)

[kyle-sexton]

Summary

Agent-driven PRs created through /source-control:pull-request create assemble their body from the skill's own template and ship it via gh pr create --body, which fully overrides .github/pull_request_template.md (cli/cli#10751). The assembled skeleton had ## Summary / ## Test plan but no ## Related section, so PRs in a repo enforcing a pr-issue-linkage-style contract (non-empty ## Related + a native closing keyword) failed the gate on first push and burned a red-CI round-trip. This is the create-flow half of the same gap #462 closed for the web/editor authoring path via the repo PR template.

Fix

In plugins/source-control/skills/pull-request/reference/create.md §2.4.1, the body-assembly template now emits a ## Related section defaulting to the literal N/A (non-empty by default; replace with Refs #N references to related-but-not-closed PRs/ADRs/decisions when they exist). It pairs with the already-always-present ${CLOSES_LINE} closing keyword — populated by §2.4.0 for every branch shape and asserted by the §2.4.2 pre-create gate — so both halves of the contract are scaffolded up front. Surrounding §2.4.1 prose documents the two scaffolds and flags the opt-out asymmetry: a bare Refs #N does not satisfy a validator's closing-keyword half (only a real keyword or a No linked issue / No related issue: phrase does). plugin.json bumped 0.12.0 → 0.12.1 (patch — contract fix to an existing flow) with a matching CHANGELOG entry.

Verification

The exact contract was read from the pinned reusable workflow source (melodic-software/ci-workflows/.github/workflows/pr-issue-linkage.yml@90f1c54, the SHA this repo's .github/workflows/pr-issue-linkage.yml pins). It runs two independent checks against the HTML-comment-stripped body:

1. ## Related section present (/^##\s+related$/i) AND non-empty after trim.
2. A closing keyword /\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s*(?:[\w.-]+\/[\w.-]+)?#\d+\b/i OR the marker /\bno (?:linked|related) issue\b/i.

The updated template, assembled with a branch-derived Closes #N, produces:

Closes #487

## Summary
...

## Test plan
- ...

## Related
N/A

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Mapped against the two checks (simulated with the validator's own regexes):

• Check 1 — heading ## Related matches ^##\s+related$; extracted section content is N/A → non-empty → pass.
• Check 2 — Closes #487 matches the closing-keyword regex (match: Closes #487) → pass.

Both halves are green on first push, no red-CI round-trip.

Known adjacent gap (out of scope, flagged for a maintainer decision): §2.4.0 offers Refs #N as a standalone opt-out and §2.4.2's OPTOUT_REGEX accepts it, but the real validator's closing-keyword half does not honor a bare Refs #N — only a real keyword or a No linked issue / No related issue: phrase. A Refs #N-only PR would still clear this skill's local gate and then fail pr-issue-linkage. This PR does not change the opt-out mechanism (that is a contract-shaped decision); it documents the asymmetry in §2.4.1 so the mismatch is visible. Recommend a follow-up to reconcile the opt-out marker set with the validator.

Closes #487

Related

• source-control/repo: PRs fail pr-issue-linkage (missing ## Related) — no template scaffolds the required sections #462 — the sibling half of this gap (repo .github/pull_request_template.md covering the web/editor authoring path); this PR covers the /source-control:pull-request create flow half.
• This PR body is itself a live example of the scaffold: a non-empty ## Related section plus a Closes #487 closing keyword, exactly the two-part skeleton the fix now emits.

🤖 Generated with a Claude Code implementation subagent (issue #487)

[claude]

Claude finished @kyle-sexton's task in 1m 25s —— View job

---

Code Review

• Gather context
• Read changed files
• Review for correctness, security, and CLAUDE.md alignment
• Post review findings

---

Overall: Focused, well-reasoned fix. The change is minimal (adding 4 lines to the body template plus documentation prose), correctness is solid, and security of the shell construction is maintained. One pre-existing issue is worth a follow-up call-out; everything else looks good.

---

Correctness

Template addition (create.md L173–175)

The ## Related\nN/A block is placed correctly inside the quoted heredoc and will produce exactly the section the pr-issue-linkage validator expects:

• ## Related matches /^##\s+related$/i ✓
• N/A is non-empty after trim ✓

Position (after ## Test plan, before attribution) is consistent with the repo's own .github/pull_request_template.md convention established by #462. ✓

Opt-out asymmetry documentation (create.md L196–201)

The prose accurately describes both scaffolds and correctly flags the known gap: §2.4.2's OPTOUT_REGEX accepts Refs #N, but the real validator's closing-keyword half does not — a Refs #N-only PR would clear the local gate and still fail CI. The documentation is precise.

That asymmetry is pre-existing (introduced when §2.4.0's orphan-PR prompt was written, not by this PR) and intentionally deferred here. The inline documentation makes the mismatch visible to maintainers and future contributors, which is the right call for a patch-scoped fix. A follow-up should either:

• Tighten OPTOUT_REGEX to exclude bare Refs #N (gate then rejects it, forcing user to the No related issue: path), or
• Keep the opt-out but add a warning in §2.4.2 that Refs #N will clear the local gate but may still fail the repo validator.

The PR description already recommends this — flagging here just to keep it visible. Fix this →

---

Security

No new concerns introduced. The critical property is preserved:

The ## Related\nN/A content is inside the quoted heredoc (<<'EOF'), so it is completely inert — no variable expansion, no command substitution. The ${CLOSES_LINE} splice happens outside, via parameter expansion + string concatenation (L188–189), which prevents shell injection from user-supplied prompt input regardless of what CLOSES_LINE contains. The explanatory comment at L192 accurately documents why this construction is safe. ✓

---

Plugin versioning & CHANGELOG

• 0.12.0 → 0.12.1: correct semver — this is a patch (contract fix to an existing flow, no new API surface). ✓
• CHANGELOG entry is accurate, thorough, and correctly references the sibling fix (source-control/repo: PRs fail pr-issue-linkage (missing ## Related) — no template scaffolds the required sections #462). ✓

---

CLAUDE.md alignment

• Repo-agnostic: no hardcoded paths or repo-specific values. ✓
• Plugin-form-safe: no ../ reach-outs, no out-of-plugin references. ✓
• Versioned with explicit semver bump. ✓
• Change is narrowly scoped to the gap it fixes — no unrelated cleanup. ✓

---

Summary: Approve. The fix is correct, the shell construction is safe, and the known gap is properly documented and deferred rather than silently ignored. The only actionable item is the pre-existing OPTOUT_REGEX asymmetry, which deserves a targeted follow-up issue.

[kyle-sexton]

Follow-up filed for the opt-out marker asymmetry noted in this PR's body / create.md §2.4.1: #630.

[kyle-sexton]

Post-green review classification

Finding	Severity	Classification	Action
Pre-existing OPTOUT_REGEX asymmetry (Refs #N clears local gate, not the real validator)	minor	VALID, deferred	Not fixed here (pre-existing, out of this patch's scope per reviewer's own assessment) — follow-up filed as #630 before this review pass, cited in ## Related.

No blocking findings. Security review confirmed heredoc quoting keeps the new content inert. CI green (16/16). Flipping to ready for review.

[claude]

Claude finished @kyle-sexton's task in 1m 24s —— View job

---

PR Review

• Read changed files
• Verify correctness of template change
• Check security of shell construction
• Validate version bump and CHANGELOG
• Post final review

---

Verdict: Approve. Minimal, correct, and safe. The earlier review findings are all resolved or properly deferred. No new issues found in this pass.

---

Template change — create.md L174–176

+## Related
+N/A
+
 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Three things to verify and all three check out:

1. Heredoc isolation: The addition is inside <<'EOF' (single-quoted), so ## Related\nN/A is completely inert — no expansion, no substitution. ✓
2. Validator compatibility: ## Related matches /^##\s+related$/i; N/A is non-empty after trim — both halves of the pr-issue-linkage check pass. ✓
3. Section ordering: After ## Test plan, before attribution — consistent with the repo's own .github/pull_request_template.md established by source-control/repo: PRs fail pr-issue-linkage (missing ## Related) — no template scaffolds the required sections #462. ✓

Prose documentation — create.md L196–201

The "Linkage scaffolds — always emitted" block and the opt-out asymmetry note are accurate. Notably:

• The closing-keyword scaffold and ## Related scaffold are correctly characterized as mirroring the two-part contract.
• The asymmetry note (Refs #N clears the local gate via OPTOUT_REGEX but does not satisfy the validator's closing-keyword half) is factually correct and appropriately scoped — documented here, deferred to source-control:pull-request: bare 'Refs #N' opt-out clears the skill's local gate but not the real pr-issue-linkage validator #630 for resolution.

Shell injection defense — create.md L181–189

No change to the construction around ${CLOSES_LINE}. The critical invariant — quoted heredoc keeps body content inert, parameter expansion + concat keeps user input literal — is unchanged and intact. ✓

Version bump and CHANGELOG

• 0.12.0 → 0.12.1: correct semver for a patch (contract fix to existing flow, no new API surface). ✓
• CHANGELOG entry at CHANGELOG.md L6–23 is thorough and accurate; cites the sibling fix (source-control/repo: PRs fail pr-issue-linkage (missing ## Related) — no template scaffolds the required sections #462) and the gh pr create --body override root cause (How do I turn off "Prepend commit bodies in gh pr create with templates #1570"? cli/cli#10751). ✓

CLAUDE.md alignment

• Repo-agnostic: no hardcoded paths or project-specific values. ✓
• Plugin-form-safe: all references stay within ${CLAUDE_PLUGIN_ROOT}. ✓
• Narrowly scoped: touches only the gap it closes. ✓

---

Pre-existing deferred item: The OPTOUT_REGEX asymmetry (§2.4.2 accepts Refs #N, real validator does not) is pre-existing, documented in §2.4.1, and tracked in #630. Out of scope for this patch.

[kyle-sexton]

Control tower decide-and-log (operator veto window). Digest flagged one plan deviation: #487's plan said to promote the ${CLOSES_LINE} conditional so the closing keyword is always scaffolded; the PR instead documents that the line is already always-populated (§2.4.0 orphan-PR prompt fills it; §2.4.2 pre-create gate asserts it before gh pr create). Digest verified that flow at head and the acceptance criterion (first-push body satisfies pr-issue-linkage) holds. Tower accepts the interpretation: same guarantee, less code motion, and the pre-create assert is the stronger invariant. Reversible — if the operator prefers the literal promotion, file the delta as a follow-up. A merge-main + 0.13.1 re-bump is in flight to clear the version conflict.

[claude]

Claude finished @kyle-sexton's task in 1m 27s —— View job

---

PR Review

• Gather context
• Read changed files at HEAD (f3e942a)
• Verify correctness of template change
• Check security of shell construction
• Validate version bump and CHANGELOG
• Post final review

---

Verdict: Approve. The synchronize event is a single maintenance commit (chore(source-control): merge main, re-bump to 0.13.1) that resolves a version conflict; the core fix in create.md is unchanged from the prior two review passes. All previous findings are still resolved or properly deferred. No new issues.

---

What changed since the last review pass (3b14747 → f3e942a)

The synchronize event contained exactly one commit:

File	Change
plugin.json	"version": "0.12.1" → "0.13.1"
CHANGELOG.md	Top-level header updated to ## [0.13.1]; ## [0.13.0] block from main inserted below
create.md	Unchanged — identical to the file reviewed in the two prior passes

---

Version bump correctness

The re-bump is correct. During the review window, main advanced from 0.12.0 → 0.13.0 (the babysit authorship/classifier refactor). This PR's original commit had targeted 0.12.1. The resolution:

• 0.13.0 — already on main (not part of this PR)
• 0.13.1 — this PR's patch fix applied on top → correct semver semantics ✓

The ## [0.13.0] CHANGELOG block is brought in verbatim from main and is not authored by this PR, so no additional review is needed for its content. ✓

---

Core fix — create.md L174–176

Unchanged from prior review. Re-verified at HEAD:

• ## Related\nN/A is inside <<'EOF' (single-quoted heredoc) — completely inert, no expansion ✓
• ## Related matches /^##\s+related$/i; N/A is non-empty after trim — both halves of pr-issue-linkage pass ✓
• Section position (after ## Test plan, before attribution) matches repo convention established by source-control/repo: PRs fail pr-issue-linkage (missing ## Related) — no template scaffolds the required sections #462 ✓

Shell injection defense — create.md L181–189

Unchanged. Quoted heredoc + parameter-expansion concat is intact. ${CLOSES_LINE} from user input remains literal regardless of content. ✓

Prose documentation — create.md L196–201

Unchanged. "Linkage scaffolds — always emitted" block and opt-out asymmetry note are accurate. The Refs #N / validator-gap is documented here and tracked in #630. ✓

CLAUDE.md alignment

• Repo-agnostic, no hardcoded paths ✓
• Plugin-form-safe, no ../ reach-outs ✓
• Explicit semver bump with correct patch semantics ✓
• Narrowly scoped to the gap it closes ✓

---

Pre-existing deferred item: OPTOUT_REGEX asymmetry (§2.4.2 accepts Refs #N; real validator does not) is documented in §2.4.1 and tracked in #630. Out of scope for this patch.