pr

Create Pull Request

Full PR creation workflow with multi-faceted review, quality gates, and structured PR body. Follows Explore > Plan > Code > Verify loop.

Required Skills

• llm-operator-principles — foundational operator stance: convergence = zero findings, in-PR fixes by default, no calendar-time estimates, narrow escalation triggers. MUST be consulted before any other phase
• pr-lifecycle — pre-flight, PR body, reviewer suggestion
• code-review-methodology — 6-facet review synthesis
• capability-discovery — detect quality commands and agents
• holdout-validation — cross-reference self-review claims against file state (Phase 3)

References

• references/escalation-format.md — canonical six-field structure used by Phase 4's visual-verification BLOCKED escalation and any other Proactive-Autonomy escalation surfaced during PR creation
• references/finding-schema.md — canonical row shape every reviewer agent dispatched in Phase 3 emits

Phase 1: EXPLORE

# Output: `###`-headed sections + KEY=value per
# `references/command-output-format.md`. STATE=blocked when on default branch
# (can't create a PR from main); STATE=ok otherwise.

echo "### Branch Context"
BRANCH=$(git branch --show-current 2>/dev/null)
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
echo "BRANCH=$BRANCH"
echo "DEFAULT_BRANCH=$DEFAULT_BRANCH"

if [ "$BRANCH" = "$DEFAULT_BRANCH" ]; then
  echo "STATE=blocked"
  echo "ERROR=Cannot create PR from default branch"
else
  echo "STATE=ok"

  # Section: Branch Delta vs Default
  echo ""
  echo "### Branch Delta"
  echo "COMMITS_AHEAD=$(git rev-list --count "$DEFAULT_BRANCH"..HEAD 2>/dev/null || echo "0")"
  # Cache the porcelain count once — previously invoked twice in adjacent
  # lines (count + gate on the UNCOMMITTED_LINE listing).
  UNCOMMITTED_COUNT=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
  echo "UNCOMMITTED_COUNT=$UNCOMMITTED_COUNT"
  [ "$UNCOMMITTED_COUNT" != "0" ] && git status --short 2>/dev/null | head -20 | sed 's/^/UNCOMMITTED_LINE=/'
  echo ""
  echo "#### Diff stat"
  DIFF_STAT=$(git diff --stat "$DEFAULT_BRANCH"...HEAD 2>/dev/null)
  if [ -z "$DIFF_STAT" ]; then
    echo "STATE=empty"
  else
    printf '%s\n' "$DIFF_STAT" | sed 's/^/DIFF_STAT=/'
  fi

  # Section: Issue Context (extracted from branch name `feature/issue-N-...`)
  echo ""
  echo "### Issue Context"
  ISSUE_NUM=$(echo "$BRANCH" | grep -oE 'issue-[0-9]+' | grep -oE '[0-9]+')
  # Quote parenthesized fallback per command-output-format.md rule 2 (values
  # with whitespace/parens must be double-quoted scalars).
  echo "ISSUE_NUM=${ISSUE_NUM:-\"(none)\"}"
  if [ -n "$ISSUE_NUM" ]; then
    gh issue view "$ISSUE_NUM" --json title,body,labels --jq '
      "ISSUE_TITLE=\"\(.title)\"\nISSUE_LABELS=\([.labels[].name] | join(","))\nISSUE_BODY_LENGTH=\(.body | length)"
    ' 2>/dev/null
  fi

  # Section: Existing PR Check
  echo ""
  echo "### Existing PR Check"
  # Capture gh exit separately. The `|| echo "0"` fallback fails to fire when
  # gh succeeds but returns "" (impossible here — gh returns [] for empty
  # success) OR when jq receives empty input from a failed gh call (jq 1.8
  # produces no output + exit 0, so `||` doesn't trigger and the section
  # silently leaks `EXISTING_PR_COUNT=`).
  EXISTING=$(gh pr list --head "$BRANCH" --state open --json number,url 2>/dev/null); GH_EXIT=$?
  if [ $GH_EXIT -ne 0 ]; then
    echo "EXISTING_PR_COUNT=0"
    echo "STATE=unavailable"
  else
    EXISTING_COUNT=$(echo "$EXISTING" | jq 'length' 2>/dev/null)
    [ -z "$EXISTING_COUNT" ] && EXISTING_COUNT=0
    echo "EXISTING_PR_COUNT=$EXISTING_COUNT"
    if [ "$EXISTING_COUNT" = "0" ]; then
      echo "STATE=empty"
    else
      echo "$EXISTING" | jq -r '.[] | "EXISTING_PR=number=\(.number) url=\(.url)"' 2>/dev/null
    fi
  fi

  # Section: Decision Journal
  echo ""
  echo "### Decision Journal"
  JOURNAL_DIR=".decisions"
  if [ -n "$ISSUE_NUM" ] && [ -f "$JOURNAL_DIR/issue-$ISSUE_NUM.md" ]; then
    echo "JOURNAL_FILE=$JOURNAL_DIR/issue-$ISSUE_NUM.md"
    echo "JOURNAL_BYTES=$(wc -c < "$JOURNAL_DIR/issue-$ISSUE_NUM.md" | tr -d ' ')"
    echo ""
    echo "#### Journal contents"
    cat "$JOURNAL_DIR/issue-$ISSUE_NUM.md"
  else
    echo "STATE=empty"
  fi

  # Section: FlowGoal State (v3) — gate on goal existence.
  # Surface the active goal's lifecycle so Phase 4 can gate PR creation on goal
  # achievement WHEN a goal exists; a branch with no goal is not blocked. The
  # gate is disabled when flow.goals.enabled is false or goalCreation is off,
  # preserving the v2 (requireGoalForStart:false) UX.
  echo ""
  echo "### FlowGoal State"
  HELPER="$(__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/cascade-resolve.sh"
  # Migration-aware: goalCreation wins; else map legacy requireGoalForStart
  # (true->always, false->off); else null so the cascade default (auto) applies.
  GOAL_MODE=$("$HELPER" --default "auto" '.flow.goals.goalCreation // (if .flow.goals.requireGoalForStart == true then "always" elif .flow.goals.requireGoalForStart == false then "off" else null end)' 2>/dev/null)
  case "$GOAL_MODE" in auto|always|off) ;; *) GOAL_MODE="auto" ;; esac
  ENABLED=$("$HELPER" --default "true" '.flow.goals.enabled' 2>/dev/null)
  # Empty means cascade-resolve itself failed — honor enabled-by-default intent
  # rather than fail-open to a silently disabled gate.
  [ -z "$ENABLED" ] && ENABLED="true"
  if [ "$ENABLED" != "true" ] || [ "$GOAL_MODE" = "off" ]; then
    echo "STATE=disabled"
    echo "REASON=flow.goals.enabled is false or goalCreation is off"
  else
    ACTIVE_GOAL_HELPER="$(__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-active-goal.sh"
    if [ ! -x "$ACTIVE_GOAL_HELPER" ]; then
      echo "STATE=unavailable"
      echo "REASON=flow-active-goal.sh missing or non-executable"
    else
      # --allow-terminal: surface an already-`achieved` goal so the GATE=pass
      # branch below is reachable (the helper is active-only otherwise).
      # --branch-strict: resolve ONLY a goal owning the current branch, never a
      # stale active goal on another branch.
      GOAL_STATUS=$("$ACTIVE_GOAL_HELPER" --status --allow-terminal --branch-strict 2>/dev/null); GOAL_EXIT=$?
      case "$GOAL_EXIT" in
        0)
          GOAL_ID=$("$ACTIVE_GOAL_HELPER" --id --allow-terminal --branch-strict 2>/dev/null)
          echo "STATE=ok"
          echo "GOAL_ID=$GOAL_ID"
          echo "GOAL_LIFECYCLE=$GOAL_STATUS"
          if [ "$GOAL_STATUS" = "achieved" ]; then
            echo "GATE=pass"
          else
            echo "GATE=block"
          fi
          ;;
        1)
          # No active goal on this branch — gate not applicable: the gate keys
          # on goal existence. PR creation proceeds; a goal-less PR is not blocked.
          echo "STATE=none"
          echo "GATE=pass"
          echo "REASON=no active FlowGoal for this branch — gate not applicable"
          ;;
        3)
          echo "STATE=degenerate"
          echo "GATE=block"
          echo "REASON=multiple active goals on the current branch — run /flow:goal history and clear extras"
          ;;
        *)
          echo "STATE=unavailable"
          echo "GATE=block"
          echo "REASON=flow-active-goal.sh exited $GOAL_EXIT"
          ;;
      esac
    fi
  fi
fi

true