merge

Merge PR #$ARGUMENTS

Tier 3 operation — always requires human confirmation. This is non-negotiable even in autonomous mode.

Required Skills

• llm-operator-principles — operator stance (inlined above): convergence is zero findings, fix in this PR, no calendar-time estimates, escalate only for true decisions
• merge-and-release — prerequisite verification, merge execution
• run-state-management — FlowRun/FlowActivity records at phase boundaries (v3 runtime)

# Inline the Required Skills above so their rules are in context before the
# first phase runs (commands cannot preload skills from frontmatter). Ambient
# skills load whole; dispatched skills (context: fork / agent:) load their
# `## Contract` section and run in full when this command invokes
# Skill(<name>). Output per `references/command-output-format.md`.
"$(__fr="${CLAUDE_PLUGIN_ROOT:-}";[ -x "$__fr/bin/cascade-resolve.sh" ]||__fr=$({ echo plugins/flow;ls -d "$HOME"/.claude/plugins/cache/synapti-marketplace/flow/*/ 2>/dev/null|sort -Vr;echo "$HOME/.claude/plugins/marketplaces/synapti-marketplace/plugins/flow"; }|while read -r __p;do [ -x "${__p%/}/bin/cascade-resolve.sh" ]&&{ echo "${__p%/}";break;};done);echo "$__fr")/bin/flow-load-skills.sh" llm-operator-principles merge-and-release run-state-management

true

References

• references/escalation-format.md — canonical six-field structure used by Phase 2's conflict-resolution escalation and Phase 3's merge-confirm prompt

Phase 1: Verify Prerequisites

# Take the first whitespace-separated token; accept only if it is all digits.
# Trailing context (e.g., "104 (verify ledger gate)") is fine — first-token
# extraction handles it. A non-numeric token (e.g., "foo42" or "evil;rm") is
# rejected with empty PR_NUM so it never reaches the prompt context or any
# downstream shell. Matches the pattern in brainstorm.md / design.md.
#
# Output: `###`-headed sections + KEY=value per
# `references/command-output-format.md`. STATE=blocked on bad input;
# downstream Phase 2 reads each named field directly.
_RAW="$ARGUMENTS"  # Claude Code substitutes the bare arg token, not bash parameter-expansion
ARG1="${_RAW%% *}"
case "$ARG1" in
  ''|*[!0-9]*) PR_NUM="" ;;
  *) PR_NUM="$ARG1" ;;
esac

echo "### PR Reference"
if [ -z "$PR_NUM" ]; then
  echo "STATE=blocked"
  echo "ERROR=PR number required (all-digit). Usage: /flow:merge <pr-number>"
else
  echo "STATE=ok"
  echo "PR_NUM=$PR_NUM"

  # Section: PR Status
  echo ""
  echo "### PR Status"
  gh pr view "$PR_NUM" --json reviewDecision,statusCheckRollup,mergeable,mergeStateStatus,title,headRefName --jq '
    [.statusCheckRollup[]? | select(.__typename == "CheckRun")] as $checks |
    (if (.reviewDecision // "") == "" then "(none)" else .reviewDecision end) as $review |
    "TITLE=\"\(.title)\"\nHEAD_BRANCH=\(.headRefName)\nMERGEABLE=\(.mergeable)\nMERGE_STATE_STATUS=\(.mergeStateStatus)\nREVIEW_DECISION=\($review)\nCHECKS_PASSED=\($checks | map(select(.conclusion == "SUCCESS")) | length)\nCHECKS_FAILED=\($checks | map(select(.conclusion == "FAILURE")) | length)\nCHECKS_TOTAL=\($checks | length)"
  ' 2>/dev/null

  # Section: Reviews — one labeled line per review
  echo ""
  echo "### Reviews"
  # Capture gh exit separately; gh failure must surface as STATE=unavailable
  # rather than collapse to STATE=empty (the merge gate must close, not open,
  # when reviews can't be read).
  REVIEWS_JSON=$(gh pr view "$PR_NUM" --json reviews --jq '.reviews' 2>/dev/null); GH_EXIT=$?
  if [ $GH_EXIT -ne 0 ]; then
    echo "REVIEW_COUNT=0"
    echo "STATE=unavailable"
  else
    REVIEW_COUNT=$(echo "$REVIEWS_JSON" | jq 'length' 2>/dev/null)
    [ -z "$REVIEW_COUNT" ] && REVIEW_COUNT=0
    echo "REVIEW_COUNT=$REVIEW_COUNT"
    if [ "$REVIEW_COUNT" = "0" ]; then
      echo "STATE=empty"
    else
      echo "$REVIEWS_JSON" | jq -r '.[] | "REVIEW=state=\(.state) author=@\(.author.login) at=\(.submittedAt)"' 2>/dev/null
    fi
  fi

  # Section: Unresolved Conversations (GraphQL — reviewThreads not in REST)
  echo ""
  echo "### Unresolved Conversations"
  REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
  OWNER=$(echo "$REPO" | cut -d/ -f1)
  NAME=$(echo "$REPO" | cut -d/ -f2)
  UNRESOLVED_COUNT=$(gh api graphql -f query="query { repository(owner: \"$OWNER\", name: \"$NAME\") { pullRequest(number: $PR_NUM) { reviewThreads(first: 100) { nodes { isResolved } } } } }" --jq '[.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false)] | length' 2>/dev/null); GH_EXIT=$?
  # Closed-vocab contract: emit STATE=unavailable as a separate sentinel rather
  # than encoding unavailability as the value of UNRESOLVED_COUNT.
  if [ $GH_EXIT -ne 0 ] || [ -z "$UNRESOLVED_COUNT" ]; then
    echo "UNRESOLVED_COUNT=0"
    echo "STATE=unavailable"
  else
    echo "UNRESOLVED_COUNT=$UNRESOLVED_COUNT"
  fi

  # Section: Stale Approval Check
  echo ""
  echo "### Stale Approval Check"
  gh pr view "$PR_NUM" --json reviews,commits --jq '
    ([.reviews[] | select(.state == "APPROVED")] | sort_by(.submittedAt) | last | .submittedAt // "none") as $la |
    (.commits | last | .committedDate) as $lc |
    "LAST_APPROVAL=\($la)\nLAST_COMMIT=\($lc)\nSTALE=\(if $la == "none" then "n/a" elif $la < $lc then "true" else "false" end)"
  ' 2>/dev/null

  # Section: Finding-ledger seed (full gate runs in next ! block)
  echo ""
  echo "### Finding-Ledger Seed"
  # DIAGNOSTIC PREVIEW ONLY — the authoritative gate runs in the next ! block and
  # scans both streams with trust filtering. This seed exists so the assessment can
  # report what markers are reachable before the gate runs.
  #
  # Markers live on TWO different GitHub objects (see references/finding-ledger-parser.md):
  #   - FLOW_REVIEW_CYCLE     → PR review bodies     (repos/.../pulls/N/reviews)
  #   - FLOW_RESOLUTION_CYCLE → PR/issue comments    (repos/.../issues/N/comments)
  # A seed that scans only one stream undercounts: a PR whose only marker is a
  # FLOW_REVIEW_CYCLE in a review body would report SEED_MARKER_COUNT=0 even though the
  # gate would find it. Scan both and union the hits.
  #
  # The select requires a digit after the colon (FLOW_*_CYCLE:[0-9]) so a "marker" is, by
  # definition, NAME:<cycle-number>. This excludes both bare prose mentions of the marker
  # NAME and unsubstituted-placeholder prose like `FLOW_REVIEW_CYCLE:{N}` (which the new
  # self-review template carries in its format-guide comment), so neither inflates the
  # count nor produces a spurious diagnostic. The seed is intentionally a touch stricter
  # than the gate's `test("FLOW_*_CYCLE:")` select — the gate tolerates prose by extracting
  # an empty FINDINGS list, whereas a human-facing preview should only count real markers.
  #
  # Capture gh exit separately per endpoint. Same reason as the Reviews section: the
  # merge gate must close (STATE=unavailable) rather than open (STATE=empty) when
  # markers can't be read.
  SEED_COMMENTS=$(gh api "repos/$REPO/issues/$PR_NUM/comments" --jq '[.[] | select(.body | test("FLOW_RESOLUTION_CYCLE:[0-9]|FLOW_REVIEW_CYCLE:[0-9]")) | {id, body, surface: "issue-comments"}]' 2>/dev/null); GH_EXIT_C=$?
  SEED_REVIEWS=$(gh api "repos/$REPO/pulls/$PR_NUM/reviews" --jq '[.[] | select(.body | test("FLOW_RESOLUTION_CYCLE:[0-9]|FLOW_REVIEW_CYCLE:[0-9]")) | {id, body, surface: "reviews"}]' 2>/dev/null); GH_EXIT_R=$?
  echo "SEED_SCANNED=reviews,issue-comments"
  if [ $GH_EXIT_C -ne 0 ] || [ $GH_EXIT_R -ne 0 ]; then
    echo "SEED_MARKER_COUNT=0"
    echo "STATE=unavailable"
    echo "SEED_UNAVAILABLE=comments_exit=$GH_EXIT_C reviews_exit=$GH_EXIT_R"
  else
    # Union both streams into one array for counting + per-marker emission. Capture jq's
    # exit so a malformed-JSON operand fails CLOSED (STATE=unavailable) rather than open:
    # without this, a jq error swallowed by 2>/dev/null leaves SEED_JSON empty and the
    # block would mislabel a real marker stream as STATE=empty ("no markers"). Mirrors the
    # per-endpoint fail-closed posture above. `add // []` still tolerates an empty/null
    # operand (the normal "one stream has no markers" case) without erroring.
    SEED_JSON=$(printf '%s\n%s\n' "$SEED_COMMENTS" "$SEED_REVIEWS" | jq -s 'add // []' 2>/dev/null); SEED_JQ_EXIT=$?
    if [ $SEED_JQ_EXIT -ne 0 ]; then
      echo "SEED_MARKER_COUNT=0"
      echo "STATE=unavailable"
      echo "SEED_UNAVAILABLE=union_jq_exit=$SEED_JQ_EXIT"
    else
      # Capture the count's jq exit too, for the same fail-closed reason — a length()
      # failure must not collapse to a false STATE=empty.
      SEED_COUNT=$(echo "$SEED_JSON" | jq 'length' 2>/dev/null); SEED_COUNT_EXIT=$?
      if [ $SEED_COUNT_EXIT -ne 0 ]; then
        echo "SEED_MARKER_COUNT=0"
        echo "STATE=unavailable"
        echo "SEED_UNAVAILABLE=count_jq_exit=$SEED_COUNT_EXIT"
      else
        [ -z "$SEED_COUNT" ] && SEED_COUNT=0
        echo "SEED_MARKER_COUNT=$SEED_COUNT"
        if [ "$SEED_COUNT" = "0" ]; then
          # Genuinely absent on both surfaces (no NAME:<digits> marker reachable).
          echo "STATE=empty"
        else
          # The select guarantees every row has FLOW_*_CYCLE:<digits>, so scan always
          # matches; `last` takes the real marker (typically the end-of-body HTML comment)
          # when a body also carries prose references earlier.
          echo "$SEED_JSON" | jq -r '.[] |
            ([.body | scan("FLOW_(RESOLUTION|REVIEW)_CYCLE:([0-9]+)")] | last) as $last |
            "SEED=id=\(.id) surface=\(.surface) kind=\($last[0]) cycle=\($last[1])"
          ' 2>/dev/null
        fi
      fi
    fi
  fi
fi

true