source-control: PR pipeline states, review venue, findings lane and statuses #7576

Parent

Refs #7555. Source: PLAN Phase 8, topic poteto-review. Thread: PR pipeline (source-control; save
point, draft, ready, statuses, review venue, merge queue), except its merge setups, which the Merge
authority thread carries.

Depends on

• config-cascade: settings resolution and convention home #7571 Settings resolution and convention home (gates every slice except a and c)
• Pending, set on the slices when filed: slice a (pr-states) is blocked by every Phase 2 slice except
  intent-r4 (pr-pipeline: admit marked epic slices in the resolve-issue lane #7596, testing: fix the two tests the can't-fail scan flags #7597, work-items/work: guard the pull-request create reference #7598, pr-pipeline: promote admitted items to agent-ready when their last blocker closes #7599, verification/confirm: intent-lookup ladder starting from the Brief #7602, implementation: pass the PLAN.md pointer at each handoff #7603, source-control/pull-request: carry the Brief's acceptance criteria into the PR body #7604, work-items/decompose: carry the Brief's goal and constraints into each item #7605, work-items/decompose: self-contained redacted item bodies #7607); slice
  c (pre-ready-and-statuses) by slice a. Slices a and c run before the Settings thread as the
  verifier spine.

Outcome

Each PR follows one sequence: prep once, open ready, one AI review in CI, a findings lane fixes
accepted findings, deterministic checks plus changed-files review on each fix push, the verifier's
verdict on the final head, then merge.

Decisions

• PR states: save point = commits pushed, no PR; draft only on request or as a multi-session
  container; ready = complete and through local gates; setting pr_open_state default ready; the
  AGENTS.md draft section is replaced by this rule (D75, Q501; owner chose ready with Matt).
  Unfinished multi-session skills are draft containers (Q585). PRs from earlier threads open as
  drafts until slice a merges.
• One sequence per PR: prep once (format, lint, markdown cleanup, tests, local gates), open ready, one
  whole AI review in CI, findings lane fixes accepted findings, each fix push gets deterministic
  checks plus changed-files review, verifier verdict on the final head, merge queue. CI fix-docs
  off (D100, Q158). Fixed floor: a model step on synchronize reviews only changed files.
• Setting review_venue (auto/local/ci/both, default auto): one venue per PR;
  blocking-only after the first review; fix rounds capped at 3; open security, auth or data findings
  escalate (D75, Q500). Settings: review nit handling follow-up-issue; findings-lane turn cap
  judgment until measured.
• Findings lane on workflow_run of the review lanes, turn cap and escalation; every finding vetted
  with context; a harmless nit becomes a follow-up issue blocked by the PR (D75, Q512). It reconciles
  with the existing pr-feedback-dispatch.yml lane rather than adding one.
• PR template ## Merge danger (Door, Blast radius; door pre-filled from HIGH_FLOOR; Risk folded
  in), written by a separate evaluating agent; optional in the org template first (D88, Q519;
  Matt's). Deny list stays with a reason per entry; risk is a reading order, never a gate (D72,
  Q78).
• Shipping order: a pre_ready: step list with enabled flags in the source-control convention,
  read at the base branch, reported step by step on ready; writers before readers, verification last
  (D73, D77, Q504, Q507; Lauren's configurable, auditable shipping order).
• Run-once statuses: GITHUB_TOKEN statuses that skip nothing; patch-id promise deleted;
  statuses: write on the work-lane report job stands (D73, D92, Q118, Q120).
• Routines and lanes open ready PRs and never merge; only the merge lane merges; overridable by
  config or a routine's prompt (D57, D75, Q91).
• Operator review thread = instruction to implement (interview first if intent is unclear); a wait
  or hold thread is a hold; neither is merge approval (D77, Q503, Q104).
• /source-control:resolve-conflicts removed; the lane resolves conflicts after reading both sides'
  intent (a step in /source-control:pull-request's base-merge step), escalating only when both
  intents cannot hold; no message into a live session (D109, Q541, Q568). The base-merge step lands
  before the removal; pr-unblock tests update in the same slice.
• PR body: prose plus at most one code-shape view (setting PR body code view auto); a fix or new
  behavior states its check result before and after (fixed floor; combined: Matt for fixes,
  Lauren for the rest), other changes give 1-3 run-path bullets; glossary terms (D109, Q523, Q536,
  Q574).
• A revert ships as a new patch version (Q90).

Key interfaces

From the design's contracts, "Settings": "review_venue: auto (auto/local/ci/both),
repo. pr_open_state: ready, repo. pre_ready: step list with enabled flags in the
source-control convention, read at the base branch." "Review: nit handling follow-up-issue;
fix-round cap 3; blocking-only after first review; findings-lane turn cap judgment until
measured." "Other": "Marker comment TODO(#n); PR template section ## Merge danger (Door, Blast
radius)."

Variation verdicts: "Review venue: contain now; source-control review_venue setting; abstract-now
not chosen by owner (Q500)."

Conventions followed: ADR 0049, the source-control and pr-pipeline conventions.

Slices, filed when this phase starts: pr-states, review-venue-and-findings-lane,
pre-ready-and-statuses, merge-danger, and the base-merge-then-remove-resolve-conflicts slice.

Done when

• The resolve-conflicts skill directory is gone and
  rg -n 'source-control:resolve-conflicts' plugins docs .github --glob '!**/CHANGELOG.md' --glob '!.changes/**'
  finds nothing.
• rg -c '^## Open a pull request as a draft' AGENTS.md returns 0 (1 on main) and
  node --test '.github/scripts/pr-unblock/*.test.mjs' exits 0.
• Every slice sub-issue is closed by a merged PR.

Out of scope

• Merge setups and the verifier (Merge authority thread).
• The org PR template in melodic-software/.github (another repository: owner stop).

Related

• pr-pipeline: address-feedback composite activity and its leaves #7032 address-feedback composite activity (sub-issue of this thread); the Phase 2 friction log target.
• pr-pipeline: ticket-to-merge lane decisions (pr-unblock, assess-risk) and SDLC gaps #6989 ticket-to-merge lane decisions (sub-issue of this thread).
• pr-pipeline: post-V1 audit and retro of the unattended merge flow #7531 post-V1 audit and retro of the unattended merge flow (sub-issue of this thread).
• fix(pr-pipeline): work-resolve-issue admits an issue that carries a held class beside an allowed one #7491 work-resolve-issue admits a held class beside an allowed one (sub-issue of this thread).
• work-resolve-issue: run required checks in the runner, not on the model's word #7497 work-resolve-issue runs required checks in the runner (sub-issue of this thread); hardens the lane pr-pipeline: admit marked epic slices in the resolve-issue lane #7596 widens, no shared file.
• Collides with pr-pipeline: admit marked epic slices in the resolve-issue lane #7596: fix(pr-pipeline): work-resolve-issue admits an issue that carries a held class beside an allowed one #7491 and pr-pipeline: admit marked epic slices in the resolve-issue lane #7596 both edit the resolve-issue lane's class filter; pr-pipeline: admit marked epic slices in the resolve-issue lane #7596 is blocked by fix(pr-pipeline): work-resolve-issue admits an issue that carries a held class beside an allowed one #7491 so the allowlist fix lands first and the marker path is written against it.