merge-pr

Files (6)

• SKILL.md
• guide.md
• pr_signals.py · scripts/
• review_metrics.py · scripts/
• pr_signals_test.py · scripts/tests/
• review_metrics_test.py · scripts/tests/

SKILL.md (first lines)

# Merge PR

Read [guide.md](guide.md) completely: the three acceptable kinds of attribution evidence, why log
tails must not be read, and why only the latest comment round is handled all live there. Without it this skill will release red checks it caused itself.
Resolve `skill_dir` to this skill directory. All host operations use `python3 "<skill_dir>/../_bus/cli_extensions/pr_host.py"` (`pr_host`).
Run `pr_host host`; stop on an unknown host. For Codeup, read `../_bus/docs/codeup-pr-workflow.md`.

```text
INPUT = [<pr-number>] [--no-merge] [--poll-seconds N (default 30)] [--max-wait N (default 1800)]
        [--rebase-max-commits N (default 20)] [--hold-before-merge]
repo   = git rev-parse --show-toplevel
branch = git branch --show-current
pr     = the number the caller gave; when omitted, take the unique result of `pr_host find --branch <branch>`
base_branch = the PR's base branch; profile = `pr_host profile` and its `policy` object.
IF not in a Git repository OR branch is empty OR branch IN {main, master}
  STOP "merge-pr runs only on a feature branch."
========== 1. Take the signals ==========
Run:
  python3 "<skill_dir>/scripts/pr_signals.py" checks --pr <pr>
  python3 "<skill_dir>/scripts/pr_signals.py" scope  --pr <pr>
Capture: HEAD, branch, base, isDraft, mergeable, mergeStateStatus, checkCount,
pending / passed / failed / **other**, plus this PR's `topLevel` and `files`.
scope is the first-hand basis for every attribution below; get it first.
-- This section takes a single snapshot only; waiting belongs to section 3, and must come after review handling (guide.md).
On GitHub the source of truth for `checks` is `statusCheckRollup`, at **per-check** granularity; do not switch to
workflow-granularity run listings (reasons in guide.md "Per check, not per workflow").
IF checks reports `isDraft == true`
  Run: `pr_host ready --pr <pr>`, then return to this section and retake the signals; continue only after confirming `isDraft == false`.
  If it fails, STOP and report verbatim; do not skip past it.
-- Reasons in guide.md "Draft becomes ready first, no stop".
-- `checkCount == 0` does not STOP here: the 0 in the tens of seconds right after a push is temporary; the later wait handles it.
========== 1b. Converge first when diverged from origin/<base_branch> ==========
The entry is a **positive enumeration**; only these two states enter this section. It must not be written as a negation (reasons in guide.md "Why the entry must be a positive
enumeration"):
  divergent = (mergeable == "CONFLICTING")
              OR (mergeable == "MERGEABLE" AND mergeStateStatus == "BEHIND")
IF NOT divergent
  Skip this section.
The worktree must be clean (`git status --porcelain --untracked-files=all` is empty); otherwise first hand it to
`commit-and-push` to land it, or let the developer deal with it.
ahead = `git rev-list --count origin/<base_branch>..HEAD`
IF mergeStateStatus == "BEHIND":        Invoke `rebase-origin-main --base origin/<base_branch>` (pure replay, no conflicts)
ELSE IF ahead <= rebase_max_commits:    Invoke `rebase-origin-main --base origin/<base_branch>` (necessarily CONFLICTING here)
ELSE:                                   `git fetch origin` + `git merge origin/<base_branch>`
  Conflicts follow the same tiered handling as `rebase-origin-main`: shared infra (`Cargo.lock`)
  follows its shared-infra rule, and any branch change it discards is recorded in `dropped_shared_infra`; minor conflicts are resolved automatically;
  **major conflicts go to the developer**. After resolving, Invoke `commit-and-push` (route rationale in guide.md "Merge method").
IF the invoked skill asks the developer to rule on a major conflict
  STOP and relay it verbatim.
IF `dropped_shared_infra` is nonempty
  List each entry: this branch's changes to the lockfile were dropped; this must not pass silently.
Return to section 1 and retake the signals.
-- Rebase force-pushes: every old review anchor is invalidated and all CI reruns; enter this section only when truly diverged.
========== 1c. Other non-mergeable states ==========

IF mergeable == "UNKNOWN":
  This is the normal state after every push, not unmergeable. Sleep poll_seconds and return to section 1 to retake; STOP only when it is
  still `UNKNOWN` at max_wait. The only correct action is **to ask again** (guide.md "Why the entry must be a positive enumeration").

IF mergeable != "MERGEABLE"
  STOP and report mergeStateStatus. Non-mergeable states section 1b cannot handle go to the developer.

========== 2. Clear review handling first ==========

**Review before CI**: fixes from review advance HEAD and invalidate the running CI, not the other way around (see guide.md).

IF host == codeup:
  Use `pr_host comments --pr <pr> --output <run-dir>/codeup-comments.md`; wait for `aiReviewPending` to clear.
  If `openCount` is nonzero, invoke `address-review-comments pr --free-form-file <file>`, reply to each comment
  with `pr_host reply`, post the full ledger with `pr_host comment`, and retake comments. FLAG stops the flow;
  landed fixes request review and return to section 1. Continue only with no unhandled comments.
  Skip the GitHub-only review lane below and its final retake; retake Codeup comments and view before merge.

IF host == github:

  Run:
    python3 "<skill_dir>/../address-review-comments/scripts/github_review_lane.py" reviews --pr <pr>

  WHILE `everReviewed` AND NOT `coveredAtHead` AND waited < max_wait:
    Sleep poll_seconds and rerun.
  -- The semantics of the three signals and why the wait condition must be `NOT coveredAtHead` are in guide.md "The two
  --   signals of review coverage". `everReviewed == false` does not wait here (machine review may not be wired at all); report it as is.

  IF waited >= max_wait AND NOT `coveredAtHead`
    **STOP**, and say which signal was not met: if `pendingReviewers` is nonempty, report the commit each one stopped at;
    if it is empty and `headHasReview` is false, report "no review event on the current HEAD" with `reviewedOnceAt`.
    Continue only after the developer explicitly confirms; it must truly stop.

  Invoke `address-review-comments pr --github --pr <pr>`

  Fetching comments, determining rounds, adjudicating, fixing, landing and posting the ledger **all belong to it**; this skill does none of those steps for it.
  The reason `--github` uses only this one lane is in guide.md "Why only the github lane".

  Handle its return in four ways:
    FLAG                         → STOP and relay verbatim. By definition a FLAG needs the developer's call.
    landed fixes                 → return to section 1 and retake the signals (HEAD changed, CI must rerun).
    STOP because anchor is not the current HEAD → relay verbatim and wait for the review of the latest HEAD; never treat an old round as reviewed.
    `no-comments`                → nothing to do in this section; continue. A clean review is not a reason to stop.

  Finishing one round **does not mean** the reviewer agreed. `triaged` is a marker in the local ledger meaning the author did the homework; whether the reviewer
  agrees depends on its own verdict. Run:

    python3 "<skill_dir>/../address-review-comments/scripts/github_review_lane.py" verdict --pr <pr>

  The `verdict` output is **informational only**, not a release condition: author and reviewer are peers, and a rejection with first-hand counter-evidence is an equally valid
  final outcome. The convergence criterion is "the author has adjudicated every point the reviewer made on the current HEAD", judged by `fetch` — true when no new
  round is opened.

  - This round landed fixes → return to section 1. The push triggers a re-review; the next verdict is the conclusion on the new tree.
  - This round was all REJECT (each with first-hand counter-evidence in the ledger) → continue. A verdict sitting at 🟡 / 🔵 is the **expected result**, not a blocker.
  - An unhandled FLAG → STOP. That is the kind the author cannot converge on and explicitly needs the developer's call; it has nothing to do with rejection.
  -- Why 🟢 cannot be a release condition, and why this path does not need `--admin`, are in guide.md
  --   "The merge gate is 'the author adjudicated', not 'the reviewer agreed'".

  -- Sections 2/5 advance HEAD and therefore loop; continue until the merge conditions in section 6 hold, with no round cap. Hold and escalate sharp reviewer disagreements, goal changes, or destructive or outward-facing actions without existing authorization.
  -- **The convergence criterion is "nothing left to handle", not "someone reviewed"**; the loop must include one `fetch` (guide.md).

========== 3. Wait for CI to converge (wait last) ==========

From asura1234/bus, Apache-2.0.

More from asura1234/bus