PR-Context

Produces PR bodies that give reviewers (human or AI) everything needed to verify the change — without re-reading the issue or the codebase.

Prerequisites

• Context-load snapshot is complete (test commands, CI check names)
• The issue being closed is known (from issue-craft or stack-audit)
• Implementation is complete and tests pass locally

PR Body Structure

## Summary
[1-2 sentences: what changed and why]

## Closes
Closes #N

## Scope Lock
- [x] This PR stays within the issue scope
- [ ] Out-of-scope changes: [none / list]

## Changes
- `path/to/file` — [what changed, one line per file]
- `path/to/test` — [test added/modified]

## Verification
- [x] `[test command 1 from context-load]` — [N tests pass]
- [x] `[test command 2 from context-load]` — [N tests pass]
- [x] `[build command]` — build succeeds
- [x] `[typecheck command]` — no new errors

## CI Checks Expected
- [ ] `[check name 1]` (from workflow: `[workflow file]`)
- [ ] `[check name 2]` (from workflow: `[workflow file]`)

## Acceptance Criteria
- [x] [AC 1 from issue — copied verbatim]
- [x] [AC 2 from issue — copied verbatim]
- [ ] [AC 3 — if not yet verified, leave unchecked]

## Production Plan (if applicable)
- Verification: [how to verify in production]
- Rollback: [how to revert]

Rules

1. Closes #N is mandatory — every PR must reference an issue
2. AC are copied verbatim from the issue — don't paraphrase
3. Test commands are exact — from context-load, not invented
4. CI check names are real — from workflow files, not guessed
5. Scope lock is explicit — checkbox confirming no out-of-scope changes
6. Unverified AC stay unchecked — don't lie about verification status

Base Branch Detection

Do not assume the base branch is main. Detect it automatically:

1. Primary method — read the remote HEAD symbolic ref:

   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
     | sed 's@^refs/remotes/origin/@@'

2. Fallback — query the repo's default branch via gh:

   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

3. Last resort — if both fail, default to main but warn the user: "Could not detect base branch — assuming main. Verify with git branch -r."

Use the detected base branch in --base for gh pr create and in the pre-launch checklist.

Pre-Launch Checklist

Before gh pr create:

• All tests pass locally (exact commands from context-load)
• Build succeeds
• No secrets, API keys, or tokens in the diff
• PR body has Closes #N
• AC checkboxes match actual verification status
• CI check names match workflow job names
• Branch is based on the detected base branch (see Base Branch Detection)
• Branch naming follows convention (feature/, fix/, etc.)

Launch

# Detect base branch (do not assume "main")
BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
  | sed 's@^refs/remotes/origin/@@' || \
  gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')

gh pr create \
  --title "fix: flashlight uses :FireServer() instead of :Fire()" \
  --body-file /tmp/pr-body.md \
  --base "$BASE" \
  --head fix/flashlight-fireserver

Record the PR number in the progress file.

Post-Launch

• Verify CI checks start running
• If frontend-preview was used, attach the screenshot to the PR
• Monitor for scc-failing-checks or equivalent labels (if the project uses autonomous SDLC labels)

Error Handling

• gh CLI not installed: pr-context cannot create PRs without gh. Report "gh CLI not found — PR body saved to /tmp/pr-body.md. Install gh to create: https://cli.github.com/" and save the draft.
• gh not authenticated: run gh auth status. If not authed, report "gh not authenticated — run gh auth login and retry." Save the draft.
• GitHub API rate limits: if gh pr create fails with a rate limit error, save the draft and report "Rate limited — retry after [reset time]. PR body at /tmp/pr-body.md."
• Base branch detection fails: see Base Branch Detection — fall back to main with a warning. Do not silently assume main.
• Commands fail: if gh pr create fails (network, permissions, branch push failure), save the draft and report the error. Do not lose the PR body.

Example

Complete PR body for a bug fix:

## Summary
Fixed the flashlight tool to use `:FireServer()` instead of `:Fire()` so the
server authorizes the action before it replicates.

## Closes
Closes #17

## Scope Lock
- [x] This PR stays within the issue scope
- [ ] Out-of-scope changes: none

## Changes
- `src/client/Controllers/ToolController.luau` — changed `:Fire()` to `:FireServer()`
- `scripts/test_tools.luau` — added regression test for server authorization

## Verification
- [x] `lune run scripts/test_core.luau` — 26 tests pass
- [x] `selene src/` — no new lint warnings
- [x] `luau-analyze src/` — no new type errors

## CI Checks Expected
- [ ] `test (lune)` (from workflow: `.github/workflows/ci.yml`)
- [ ] `type-check (luau-analyze)` (from workflow: `.github/workflows/ci.yml`)

## Acceptance Criteria
- [x] `ToolController:activateTool()` calls `:FireServer()` instead of `:Fire()`
- [x] Regression test added in `scripts/test_tools.luau`
- [x] 26 tests pass — `lune run scripts/test_core.luau`