dpf-pr-with-dco

DPF Pull Request with DCO

DPF's PR contract is strict and non-negotiable: every change lands via PR, every commit is DCO-signed, branches are based on origin/main, PRs open only when ready to merge (not as parking places), and the overlap sweep happens before push so sibling sessions don't ship the same fix twice. This skill walks the canonical PR opening flow with all DPF gates applied.

When to use

• Implementation complete on a topic branch, build gate (vitest + typecheck + next build per AGENTS.md §5) green, ready for merge.
• Hotfix landing under a maintenance branch with the same gates.
• Doc-only change ready to land (still goes through PR per the all-changes-land-via-pr rule).

When NOT to use

• Build gate not green — finish the work first (run superpowers:verification-before-completion).
• Branch is unsigned mid-stream — fix sign-off via git commit --amend --no-edit -s (or for older commits, git rebase --signoff) BEFORE running this skill.
• PR would be a "parking place" for in-flight work — keep the branch pushed but don't open the PR. The "PR creation means ready to merge" rule is explicit in AGENTS.md §4.
• Concurrent session is already opening a PR for the same fix — coordinate (operator) before pushing.

Read first

Source	Path	What to extract
PR contract	AGENTS.md §4	Full canonical rules: branch naming, DCO, squash-and-delete, branch-guard
Build gate	AGENTS.md §5	The 4 checks that must pass before claiming "ready to merge"
Recent main	git log origin/main --oneline -20	What the base is so the PR description references real prior context
Open PRs	gh pr list --state open --limit 50	Overlap check per feedback_pr_overlap_check_before_pushing
Pre-commit hooks	.githooks/pre-commit	What runs locally vs in CI (gitleaks + typecheck local; full build CI)

Enforces

• kernel/principles/all-changes-land-via-pr — even maintainer changes.
• kernel/principles/dco-sign-off-required — every commit needs Signed-off-by:.
• kernel/principles/always-push-after-committing — local-only commits are invisible to CI.
• kernel/principles/branch-guard-before-implementation — abort if on main or detached HEAD.
• kernel/principles/one-concern-per-pr — refuse to bundle unrelated changes.

Steps

1. Branch guard. Confirm you're NOT on main and NOT detached:

   git status --short --branch
   git branch --show-current
   

   If main or (HEAD detached at ...) — STOP. Either branch off origin/main first or move work to the right branch. Never push fix work to main.

2. Overlap sweep. Per feedback_continuous_overlap_check (re-sweep before every push, not just session start):

   gh pr list --state open --limit 50 --json number,title,headRefName
   git log origin/main --since="3 days ago" --oneline
   

   If you find a sibling PR fixing the same surface, STOP and coordinate. Two PRs landing the same fix is a waste at best and a merge-conflict spiral at worst.

3. Verify build gate. Per AGENTS.md §5:

   cd apps/web && pnpm exec vitest run                # affected tests
   cd apps/web && pnpm typecheck                       # typecheck
   cd apps/web && pnpm next build                      # if epic-completion or UI surface
   

   For UX changes: drive the change against the running app (/run or /verify skill) and capture dynamic-analysis evidence.

4. DCO check. Every commit on your branch must have Signed-off-by::

   git log origin/main..HEAD --pretty=format:'%h %s%n%(trailers:only,unfold)' | grep -B1 Signed-off-by || echo "MISSING DCO"
   

   If MISSING DCO, fix with git commit --amend --no-edit -s (HEAD only) or git rebase --signoff origin/main (whole branch). Do NOT push without sign-off — DCO bot will block merge.

5. Concurrent-session safety. Stage with explicit paths (per feedback_git_commit_only_for_concurrent_sessions):

   git add <path1> <path2>          # not `git add -A` or `git add .`
   

   Even if you're sole-owner of the worktree, this is belt-and-suspenders against accidental cross-thread file sweeps.

6. Push.

   git push                          # tracks origin/<branch>
   

   -u origin <branch> only on the first push.

7. Open the PR.

   gh pr create --title "<convention>: <imperative summary>" --body "$(cat <<'EOF'
   ## Summary
   - <1-3 bullet points naming what the PR does and why>
   - <reference parent BI / epic if applicable, e.g. "BI-XXXX">
   
   ## Test plan
   - [x] vitest <target file or suite>: <N passing>
   - [x] typecheck: clean
   - [x] next build: <pass or n/a if no UI surface>
   - [x] UX verification: <dynamic-analysis report or n/a>
   
   <Any operator-context notes — overlap sweep result, dependencies, etc.>
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   

   • Title: imperative form, prefixed by repo convention (docs:, fix:, feat:, chore:, spec:). Under ~72 chars.
   • PR creation means ready to merge. If you're not, do NOT open. Push the branch as a recovery/handoff artifact and signal that the PR is pending the next milestone.

8. Report the PR URL. With the BI id (if applicable) and the build-gate evidence summary so the operator can ratify without re-running checks.

Output template

**Pull request opened.**

- PR: <URL>
- Branch: <prefix>/<slug>  (<N> commits ahead origin/main, all DCO-signed)
- Linked BI(s): <BI-XXXXXXXX>, ...
- Build gate: vitest <pass>, typecheck <pass>, next build <pass | n/a>, UX <evidence summary | n/a>
- Overlap sweep: <no overlap | named PR ids handled how>
- Ready for: <merge | review | gated on X>

Guardrails

• Never push to main directly. Branch protection enforces this on the remote, but a force push from a misconfigured local could bypass — don't try.
• Never skip -s. git commit --no-verify skips the local typecheck hook, but the DCO trailer is the bot's hard gate — there's no way to skip and merge.
• Never open a PR as a "draft handoff" or "early visibility marker." Pushed branches do that job; PRs mean ready to merge per AGENTS.md §4.
• Never bundle unrelated changes in one PR. One concern per branch, one concern per PR. If your branch accidentally accumulated two concerns, split before opening.
• Never force-push to main. And never force-push to a topic branch that's under review without telling the reviewer.
• Never use git add -A / git add . in a worktree where concurrent sessions exist. Use explicit paths.

Worked example (this session, 2026-05-24)

Three commits landed on PR #1119 from this worktree, all following this skill's flow:

• Commit b930f46b (memo draft): branched off origin/main, signed, explicit git add docs/superpowers/drafts/2026-05-24-...md, pre-commit gitleaks scan passed, pushed, PR opened with overlap sweep showing zero conflict.
• Commit 27729864 (audit report): same flow, explicit-path stage, signed, pushed to the same branch.
• Commit 560a84d8 (semantic-fallback fix): same flow, plus full vitest suite run (946/952 — 2 unrelated cold-start flakes), typecheck clean, pre-commit hook re-ran scoped typecheck which passed.

All three commits carry Signed-off-by: Mark Bodman <markdbodman@gmail.com> and Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> trailers. DCO bot accepted all three on push.

See also

• AGENTS.md §4 (Branching, Commits & PRs) — full canonical doctrine
• Predecessor skill: dpf-worktree-per-session
• Composes with: superpowers:finishing-a-development-branch (integration-shape decisions)
• Kernel principles: all-changes-land-via-pr, dco-sign-off-required, branch-guard-before-implementation