Story: Add PR management support to compass

Table of Contents

This page documents a story in Sprint 19. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Promotes the "Compass PR review management" capture (deferred from Sprint 18), keeping its UUID so existing references resolve here. Handling a PR review round today means hand-writing raw gh api invocations — paginated comment fetches, reply POSTs with the -F vs -f integer-field distinction, and GraphQL mutations to resolve threads. Every session reconstructs them from the recipe, and every mistake costs a round-trip.

Add PR management subcommands to compass that wrap the gh CLI: list, reply to, and resolve review comments first — the verbs the Handle a PR review round runbook exercises every round — with the namespace left open for the rest of the lifecycle (checks, creation with traceability, merge) as follow-on tasks.

Status

Field Value
State DONE
Parent sprint Sprint 19
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-06-05

Acceptance

  • compass review list <PR> [--detail] lists all review comments with their id, file, line, and a preview of the body; --detail shows the full body.
  • compass review reply <PR> <comment-id> "message" creates a reply to a specific review comment.
  • compass review resolve <PR> finds all unresolved threads and resolves them, with --dry-run to preview.
  • All three commands accept --owner / --repo with defaults derived from the git remote.
  • The reply command handles commit_id, path, line, side, and in_reply_to correctly (proper integer types for line and in_reply_to).
  • compass review pending [--since 30m|2h|24h|7d] [--state open|merged|closed|all] triages PRs with unattended review threads within the look-back window: critical (merged/closed — feedback was never addressed), needs-a-round (open, owned here or unowned), and fine (open, being worked in another worktree). Severity is carried by the row icon; command hints (review list, story/task compass show) use the standard colours; exit code is 0 — the output, not the exit status, carries the signal.
  • Commands are documented in compass --help and the PR review recipes/runbook are updated to use them.

Tasks

Task State Start End Description
Implement compass review commands (list, reply, resolve) DONE 2026-06-05 2026-06-05 The four review-round verbs (list, reply, resolve, pending) wrapping gh; –owner/–repo from git remote. PR #1078.
Extend compass review list to conversation-level comments DONE 2026-06-05 2026-06-05 Conversation section in review list; gh pr view –comments retired. PR #1081.
Add compass pr checks: CI status for a PR DONE 2026-06-05 2026-06-05 compass pr checks with gh exit semantics; raw gh pr checks retired from docs. PR #1084.
Add compass pr create with conventions built in DONE 2026-06-05 2026-06-05 pr record (#1084) + pr create (#1087): validated title, traceability from task/story docs, auto-record, journal stamp.
Add compass pr merge with guard rails DONE 2026-06-05 2026-06-05 Merge commit only; guards on threads/CI proven live; –force via gh –admin; worktree-safe branch cleanup. PR #1088.
Add compass pr sync: fetch main and rebase, conflict-aware DONE 2026-06-05 2026-06-05 fetch + rebase + report; –push; conflict stop-with-guidance / –abort-on-conflict. PR #1092.
pr merge: stamp the journal automatically DONE 2026-06-05 2026-06-05 Map merged head branch to task doc, derive UUIDs, journal update –state DONE; prompt keeps only judgement work.
pr merge closes the task unless –keep-open DONE 2026-06-05 2026-06-05 A merged PR means the task shipped: pr merge runs the task-done close-out (task + story row DONE, journal) on the branch's task, with –keep-open for multi-task branches and partial work.
pr merge: close out on the branch before merging DONE 2026-06-05 2026-06-05 Run task done, commit close-out on the PR branch, push, then merge — DONE rides the PR.

Decisions

  • Commands live under compass review <subcommand>, not flat compass review-list etc. — the namespace stays open for future verbs (approve, request-changes).
  • Implementation follows the existing short-circuit dispatch pattern in compass.py; the review commands get their own module compass_review.py.
  • subprocess calls gh api ... — no reimplementation of HTTP or auth.

Out of scope

  • Auto-merging or auto-approving PRs.
  • GitHub Actions / CI integration.
  • A full gh replacement — compass commands are convenience wrappers, not feature-complete API clients.

Emacs 29.1 (Org mode 9.6.6)