Close Progress PR

Contract

Prereqs:

• •Run inside the target git repo with a clean working tree.
• •git and gh available on PATH, and gh auth status succeeds.
• •Target PR body contains a docs/progress/... link under ## Progress (preferred; not None), or you pass --progress-file, or the progress file contains the PR URL.
• •If the progress is implemented via multiple PRs (stacked/split), run this on the final PR when the progress should be marked DONE.

Inputs:

• •PR number (or current-branch PR).
• •Optional: progress file under docs/progress/ referenced by the PR (use --progress-file when PR body is missing/ambiguous).
• •Optional: --keep-branch to keep the remote head branch after merge.

Outputs:

• •Progress file finalized (Status: DONE), moved to docs/progress/archived/, and indexed in docs/progress/README.md.
• •PR merged (default merge commit) and head branch deleted (remote; best-effort).
• •PR body ## Progress link patched to point to base branch (survives branch deletion).

Exit codes:

• •0: success
• •non-zero: missing progress link/file, validation failures, or git/gh command failures

Failure modes:

• •Deferred checklist items missing Reason: (fail-fast).
• •Unchecked checklist items containing invalid ~~ (fail-fast; must be full-line - [ ] ~~...~~).
• •Progress file cannot be located or moved (path mismatch, conflicts).
• •PR merge blocked (draft/checks failing/permissions).
• •PR is not progress-tracked (## Progress is None or missing); use close-feature-pr instead.

Setup

• •Ensure gh auth status succeeds.

Key rule: Progress links must survive branch deletion

After merge, GitHub often deletes the head branch. Any PR body link like:

• •https://github.com/<owner>/<repo>/blob/<head-branch>/docs/progress/...

will break.

Patch the PR body ## Progress link to point to the base branch (usually main) after merge:

• •https://github.com/<owner>/<repo>/blob/<base-branch>/docs/progress/archived/<file>.md

Key rule: Planning PRs should link to the implementation PR

If the progress file references a planning PR (explicit - Planning PR: or a docs-only progress PR under Links -> PR), ensure that planning PR body includes:

• •## Implementation PRs (preferred), or legacy ## Implementation
• •A link to this PR (append if missing; do not overwrite existing entries)

Workflow

1. •Identify the PR number
   • •Prefer current branch PR: gh pr view --json number -q .number
2. •Preflight
   • •Ensure working tree is clean: git status --porcelain=v1 should be empty
   • •Ensure checks pass (optional but recommended): gh pr checks <pr>
   • •If PR body includes Open Questions and/or Next Steps and they are not already - None, update them to the latest status before merge (resolve questions or confirm with the user, check off completed steps, link follow-ups).
3. •Locate the progress file
   • •Prefer parsing the PR body ## Progress link and extracting docs/progress/...
   • •If missing, fallback: search by PR URL inside docs/progress/:
     • •pr_url="$(gh pr view <pr> --json url -q .url)"
     • •rg -n --fixed-string "$pr_url" docs/progress -S
4. •Finalize progress
   • •Update the progress file:
     • •Auto-defer unchecked checklist items under ## Steps (Checklist) by marking them ~~...~~ (excluding Step 4 “Release / wrap-up”)
       • •Pass: - [x] ...
       • •Auto-fix: - [ ] ... → - [ ] ~~...~~
       • •Fail: unchecked item contains ~~ but is not full-line - [ ] ~~...~~
     • •For intentionally deferred / not-do items (Steps 0–3), keep the checkbox unchecked, include an explicit Reason:, and mark the item text with Markdown strikethrough (use - [ ] ~~like this~~)
     • •Set Status to DONE
     • •Update the Updated date to today
     • •Set Links -> PR to the PR URL
     • •Ensure Links -> Docs and Links -> Glossary are Markdown links (not backticks) that resolve to existing files
     • •If there are no related docs for this PR, set Links -> Docs to None (do not guess a random file)
   • •Move it to docs/progress/archived/<file>.md if not already archived
   • •Update docs/progress/README.md (move row to Archived; keep Archived sorted newest-first by Date; set PR link to [#<number>](<url>); best-effort if table format differs)
5. •Commit and push these changes to the PR branch
6. •Merge and delete branch
   • •Default merge method: merge commit
   • •gh pr merge <pr> --merge
   • •Best-effort delete remote head branch:
     • •git push origin --delete <headRefName>
7. •Post-merge: patch PR body links to base branch
   • •Get base branch: gh pr view <pr> --json baseRefName -q .baseRefName
   • •Update ## Progress to:
     • •https://github.com/<owner>/<repo>/blob/<baseRefName>/docs/progress/archived/<file>.md
8. •Post-merge: patch planning PR (when present)
   • •Extract planning PR from the progress file (Links -> Planning PR when present; otherwise infer from the pre-close Links -> PR if it points to a docs-only planning PR)
   • •Ensure the planning PR body contains:
     • •## Implementation PRs (preferred) or legacy ## Implementation
       • •Includes - [#<feature_pr_number>](<feature_pr_url>) (append if missing; do not overwrite existing entries)

Optional helper script

• •Use $CODEX_HOME/skills/workflows/pr/progress/close-progress-pr/scripts/close_progress_pr.sh in this skill folder to run a deterministic version of steps 3–8.
• •If $CODEX_HOME/skills/workflows/pr/progress/close-progress-pr/scripts/close_progress_pr.sh fails, attempt to fix the underlying cause (prefer fixing the script when it's a script bug, otherwise fix the documented prerequisites/workflow), re-run it, and explicitly report whether the fix succeeded.