ADR-0004: The orchestrator is the only PR producer under `sequant run`

Status: Accepted Date: 2026-09-30 Issue: #1247

Context

sequant run had two PR producers. The /exec skill’s “PR Creation and Verification” section ran gh pr create whether or not an orchestrator was driving it, and createPR (worktree-manager.ts) opened the PR after QA. When exec got there first, createPR found the PR and returned it untouched, so everything sequant builds for the body (the non-A+ QA note, the ready-gate report, exec’s summary, the stack manifest, the --stacked base) never reached it. When exec did not open one and a later qa-only run did, that run had no exec output, so the body was the placeholder. --no-pr only reached the orchestrator’s producer.

Decision

1. Under SEQUANT_ORCHESTRATOR the exec skill pushes the branch and opens no PR, by gh pr create or by the in-place MCP pull-request tool. createPR is the only producer.
2. createPR updates a PR that already exists for the branch (both the up-front check and the “already exists” race) instead of returning it: it pushes, then PATCHes the title and body through GitHubProvider.updatePRSync (gh api -X PATCH, not gh pr edit), and the base under --stacked.
3. Title and body are overwritten only when the existing body is empty or carries the 🤖 Generated by \sequant run“ trailer. Any other body was written by someone else and is left alone; the base is still set.
4. The last successful exec pass’s extracted summary is saved on the issue’s state (execSummary). A run with no exec pass of its own uses it.
5. createPR runs twice in a passing run: right after each successful exec pass that left commits on the branch, and again after QA. The first call creates the PR from exec’s summary. The second goes through the update path in point 2 and adds the QA note and the ready-gate report. QA reads the mutation records, the AC table and the test-plan boxes from the PR body, so the PR has to exist before QA runs. A failed after-exec call only warns; the post-QA call stays fatal (#879). An exec that declares SPEC_DIVERGENCE opens no PR. Whether that PR should be a draft until QA passes is #1246’s decision.

Options

Option A: orchestrator as the single producer (chosen)

Pros: One place builds the body; --no-pr covers every producer with no new env var. Cons: as first built, the PR opened only after QA, so QA steps that read the PR body (the SEQUANT_MUTATION record, the AC literal-diff, the settle evidence, the test-plan boxes) saw no body during an orchestrated run. QA flagged this, and the owner chose to open the PR right after exec (point 5) over teaching QA a second source (state’s execSummary), which would have touched four sites in the QA skill. Exec puts its markers in its final ## Summary so they reach the PR body.

Option B: exec opens the PR, the orchestrator only edits it

Pros: QA keeps a PR body to read. Cons: still two producers; exec cannot see --no-pr without threading another SEQUANT_* variable, and a run where exec skipped the PR still needs the orchestrator’s create path.

Option C: thread --no-pr to exec as an env var

Rejected: once exec never opens a PR under an orchestrator there is nothing for the variable to gate.

Exec summary: state vs. a branch marker

State (.sequant/state.json) is already where pr and phases live, and qa-only re-runs happen from the same checkout. A branch marker would need a commit or an existing PR first.

Consequences

• PRs left behind by pre-#1247 exec runs carry Claude Code’s trailer, not sequant’s, so their bodies are not rewritten; only the base is updated.
• A failed PATCH warns and the run keeps its PR: the PR exists, only its body is stale.
• The update path pushes before updating, so commits made after the PR was opened (a quality-loop fix) are no longer left local.