land-pr

name	land-pr
user-invocable	false
description	Helper for PR landing — rebase, push, create-or-detect PR, poll CI, optional auto-merge. Dispatched via the Skill tool by /run-plan, /commit pr, /do pr, /fix-issues pr, /draft-plan, /refine-plan, /draft-tests (and orchestrator agents landing one-off PRs). Returns state via --result-file for caller-driven fix-cycle loops. Not for direct slash invocation — humans should use /commit pr instead.
argument-hint	--branch <name> --title <title> --body-file <path> --result-file <path> [--auto] [--automerge] [--worktree-path <path>] [--landed-source <skill>] [--ci-timeout <sec>] [--no-monitor] [--pr <num>] [--issue <num>] [--tracking-id <id>]
metadata	{"version":"2026.06.15+1fd1a2"}

/land-pr — land a feature branch as a PR

/land-pr owns the rebase → push → create-or-detect → monitor → merge sequence for a feature branch that is already in a presentable state. Seven callers dispatch into this skill via the Skill tool: the four implementation callers (/run-plan, /commit pr, /do pr, /fix-issues pr) and the three drafting callers (/draft-plan, /refine-plan, /draft-tests — added per issue #581 so their worktree-committed plan/spec files reach main under landing: pr + main_protected: true). /land-pr is a helper, not a user-facing command: the API requires --body-file and --result-file, both of which only make sense when a caller has set them up. Users wanting to ship an existing branch should use /commit pr, which dispatches /land-pr internally with the right arguments.

The skill is a prose-driven procedure: when invoked, you (Claude) read this SKILL.md and execute the procedure step-by-step, calling the four deterministic scripts under scripts/ as you go. Data hand-off back to the caller is file-based via --result-file, parsed by an allow-list parser in the caller (see references/caller-loop-pattern.md).

The caller's loop pattern (idempotent re-invocation, allow-list result parsing, CI-fix-cycle agent dispatch) lives in references/caller-loop-pattern.md. The fix-cycle agent prompt template lives in references/fix-cycle-agent-prompt-template.md. Phases 2–5 of the PR_LANDING_UNIFICATION plan copy from these references.

Reporting back to the user

When this skill returns to the orchestrator (via the result file written in Step 9), the orchestrator typically composes a user-facing summary of the landing outcome. NEVER instruct the user to type /land-pr in that summary. This skill carries user-invocable: false for a reason — the slash runtime will not dispatch it from a human-typed slash command in any useful way. If the PR landed cleanly, just report the PR URL + merge status. If the PR is in a non-terminal state (CI failing, OPEN/BEHIND, rebase conflict), recommend /commit pr to retry the landing (it dispatches /land-pr internally with the right arguments), or — for low-level recovery — git push + gh pr create directly. The other 6 caller skills (/run-plan, /do pr, /fix-issues pr, /draft-plan, /refine-plan, /draft-tests) all dispatch /land-pr internally and are valid recommendations depending on the workflow that originated the PR.

When invoked

At orchestrator level only. /land-pr was loaded into your context by the Skill tool (or a direct slash invocation). Internal Agent dispatches inside /land-pr — none planned, but if added — must run at orchestrator level. Callers therefore must NOT dispatch /land-pr from inside an Agent prompt block. This is a documented contract; conformance assertions in Phase 6 verify caller skills follow it.

Argument parsing (WI 1.2)

Parse $ARGUMENTS using the bash-regex idiom that matches /do and /commit. Required: --branch, --title, --body-file, --result-file. Optional: --auto (bool, default false — unattended mode), --automerge (bool, default false — request auto-merge; implies --auto), --worktree-path, --landed-source (default land-pr), --ci-timeout (default 600), --no-monitor (skip CI poll, return after create), --pr <num> (resume mode: skip rebase/push/create, jump to monitor), --issue <num> (passes through to .zskills/landed schema), --tracking-id <id> (when present, write fulfilled.land-pr.<id> on successful merge to satisfy a parent skill's requires.land-pr.<id> marker — /run-plan PR mode passes this; the other 3 callers do not, preserving their no-fulfillment behavior).

# zsh portability (#1155): on stock macOS, Claude Code snapshots zsh and
# this fence executes under it. zsh defaults to 1-based arrays, so the
# 0-based `${ARGS[$i]}` indexing below mis-parses every arg. KSH_ARRAYS
# makes zsh arrays 0-based, matching bash. No-op under bash (ZSH_VERSION
# unset). `|| true` so a future zsh without these options can't abort.
if [ -n "${ZSH_VERSION:-}" ]; then setopt KSH_ARRAYS BASH_REMATCH SH_WORD_SPLIT 2>/dev/null || true; fi
ARGS=( "$@" )
BRANCH=""
TITLE=""
BODY_FILE=""
RESULT_FILE=""
AUTO_FLAG=false
AUTOMERGE_FLAG=false
WORKTREE_PATH=""
LANDED_SOURCE="land-pr"
CI_TIMEOUT=600
NO_MONITOR=false
PR_RESUME=""
ISSUE_NUM=""
BASE_BRANCH="main"
TRACKING_ID=""

i=0
while [ $i -lt ${#ARGS[@]} ]; do
  arg="${ARGS[$i]}"
  case "$arg" in
    --branch)         i=$((i+1)); BRANCH="${ARGS[$i]:-}" ;;
    --title)          i=$((i+1)); TITLE="${ARGS[$i]:-}" ;;
    --body-file)      i=$((i+1)); BODY_FILE="${ARGS[$i]:-}" ;;
    --result-file)    i=$((i+1)); RESULT_FILE="${ARGS[$i]:-}" ;;
    --auto)           AUTO_FLAG=true ;;
    --automerge)      AUTOMERGE_FLAG=true; AUTO_FLAG=true ;;
    --worktree-path)  i=$((i+1)); WORKTREE_PATH="${ARGS[$i]:-}" ;;
    --landed-source)  i=$((i+1)); LANDED_SOURCE="${ARGS[$i]:-}" ;;
    --ci-timeout)     i=$((i+1)); CI_TIMEOUT="${ARGS[$i]:-}" ;;
    --no-monitor)     NO_MONITOR=true ;;
    --pr)             i=$((i+1)); PR_RESUME="${ARGS[$i]:-}" ;;
    --issue)          i=$((i+1)); ISSUE_NUM="${ARGS[$i]:-}" ;;
    --base)           i=$((i+1)); BASE_BRANCH="${ARGS[$i]:-}" ;;
    --tracking-id)    i=$((i+1)); TRACKING_ID="${ARGS[$i]:-}" ;;
    *) echo "ERROR: /land-pr: unknown arg: $arg" >&2; exit 2 ;;
  esac
  i=$((i+1))
done

# Validation. Each fail-fast gate prints a discriminator line to stderr.
if [ -z "$BRANCH" ]; then
  echo "ERROR: /land-pr requires --branch" >&2; exit 2
fi
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  echo "ERROR: /land-pr: --branch must not be 'main' or 'master'" >&2; exit 2
fi
if [ -z "$TITLE" ]; then
  echo "ERROR: /land-pr requires --title" >&2; exit 2
fi
if [ "${#TITLE}" -gt 120 ]; then
  echo "ERROR: /land-pr: --title must be ≤ 120 chars (got ${#TITLE})" >&2; exit 2
fi
if [ -z "$BODY_FILE" ] || [ ! -s "$BODY_FILE" ]; then
  echo "ERROR: /land-pr: --body-file must exist and be non-empty (got '$BODY_FILE')" >&2; exit 2
fi
if [ -z "$RESULT_FILE" ]; then
  echo "ERROR: /land-pr requires --result-file" >&2; exit 2
fi
RESULT_DIR=$(dirname "$RESULT_FILE")
if [ ! -d "$RESULT_DIR" ]; then
  echo "ERROR: /land-pr: --result-file parent dir does not exist: $RESULT_DIR" >&2; exit 2
fi
if [ -n "$PR_RESUME" ] && ! [[ "$PR_RESUME" =~ ^[0-9]+$ ]]; then
  echo "ERROR: /land-pr: --pr must be numeric (got '$PR_RESUME')" >&2; exit 2
fi
if ! [[ "$CI_TIMEOUT" =~ ^[0-9]+$ ]]; then
  echo "ERROR: /land-pr: --ci-timeout must be numeric (got '$CI_TIMEOUT')" >&2; exit 2
fi

# Branch names commonly contain `/` (smoke/foo, feat/bar). Sanitize for
# use in /tmp sidecar filenames so we never accidentally create an
# unintended /tmp subdirectory. The slug is for filenames only — the
# real $BRANCH is what we pass to git/gh.
BRANCH_SLUG="${BRANCH//\//-}"

Result-file safety contract (WI 1.7)

The result file is a sequence of KEY=VALUE lines. Every value is a single-line, shell-safe token — no \n, \r, $, backticks, &, ?, #. Multi-line content (stderr text, conflict file lists) goes in sidecar files referenced by path; only the path goes in the result file.

Before writing each KEY=VALUE line, validate the value with this helper:

if [ -n "${ZSH_VERSION:-}" ]; then setopt KSH_ARRAYS BASH_REMATCH SH_WORD_SPLIT 2>/dev/null || true; fi
validate_result_value() {
  local key="$1" value="$2"
  if [[ "$value" =~ [$'\n\r$`&?#'] ]]; then
    echo "ERROR: /land-pr: result-file VALUE for $key contains forbidden characters" >&2
    return 1
  fi
}

The result file is overwritten atomically: write to $RESULT_FILE.tmp, then mv to $RESULT_FILE. Callers see either the old file or the new file, never a partial write.

Result-file schema

STATUS=created|monitored|merged|push-failed|rebase-conflict|create-failed|monitor-failed|merge-failed|rebase-failed|behind-thrash|auto-rebase-conflict|auto-rebase-blocked
PR_URL=<https-url-no-metacharacters-or-empty>
PR_NUMBER=<digits-or-empty>
PR_EXISTING=true|false
CI_STATUS=pass|fail|pending|none|skipped|unknown|not-monitored
CI_LOG_FILE=<path-or-empty>
MERGE_REQUESTED=true|false
MERGE_REASON=auto-not-requested|ci-not-passing|auto-merge-disabled-on-repo|gh-error|empty
PR_STATE=OPEN|MERGED|UNKNOWN|not-checked
REASON=<short-token-or-empty>           # e.g., rebase-conflict, network, abort-failed, auto-rebase-exhausted, auto-rebase-push-failed-rcN, mergeStateStatus-<status>, auto-rebase-unknown
CONFLICT_FILES_LIST=<path-or-empty>     # sidecar file with one conflict path per line
CALL_ERROR_FILE=<path-or-empty>         # sidecar file with stderr text from failed gh/git call
REBASE_STDERR_FILE=<path-or-empty>      # sidecar file with stderr from Step 6b auto-rebase loop

Caller parsing pattern: see references/caller-loop-pattern.md. Never source the result file — use the allow-list line-by-line parser.

Canonical .zskills/landed schema (WI 1.11)

When --worktree-path is supplied, /land-pr writes a .zskills/landed marker at <worktree>/.zskills/landed via bash "$ZSKILLS_SKILLS_ROOT/commit/scripts/write-landed.sh". The schema is canonical across all callers:

status: <required>      # landed | pr-ready | pr-ci-failing | pr-failed | conflict | pr-state-unknown
date: <required>        # ISO-8601 in configured tz: $(TZ="${TIMEZONE:-UTC}" date -Iseconds)
source: <required>      # caller skill name (run-plan, commit, do, fix-issues, land-pr)
method: <required>      # always "pr" in this plan's scope
branch: <required>      # feature branch name
pr: <optional>          # PR URL; present only after pr-push-and-create.sh succeeds
ci: <optional>          # CI_STATUS value; present only after pr-monitor.sh ran
pr_state: <optional>    # PR_STATE value; present only after pr-merge.sh ran
commits: <optional>     # space-separated SHA list of commits on the branch
issue: <optional>       # GitHub issue number; present for /fix-issues caller
reason: <optional>      # short token: rebase-conflict-too-many-files, ci-fix-cycle-exhausted, etc.
conflict_files: <optional>  # space-separated paths; present for status=conflict (small lists only)

/run-plan may write its own .zskills/landed for the pre-/land-pr "rebase-conflict-too-many-files" case (when it bails before invoking /land-pr). The schema is the same in both write paths.

Procedure (WI 1.12)

When /land-pr is invoked, run the steps below. Each step has a clear input/output contract and a clear failure mode. Compose the final result-file in step 9 from accumulated state.

Step 1 — Initialize result variables

STATUS=""
PR_URL=""
PR_NUMBER=""
PR_EXISTING=""
CI_STATUS=""
CI_LOG_FILE=""
MERGE_REQUESTED="false"
MERGE_REASON=""
PR_STATE="not-checked"
REASON=""
CONFLICT_FILES_LIST=""
CALL_ERROR_FILE=""

# Enterprise-host awareness (#1162): resolve GH_HOST from origin ONCE, up
# front, so every inline `gh` call in this skill (Step 2 resume `gh pr
# view`, Step 6b/6c auto-rebase `gh pr view --json mergeStateStatus`) and
# the gh-using scripts target the repo's ACTUAL host, not the github.com
# default. gh-host.sh is sourced (exports GH_HOST when resolvable;
# fail-open otherwise) and respects a pre-set GH_HOST.
if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/land-pr/scripts/gh-host.sh" ]; then
  . "${CLAUDE_PLUGIN_ROOT}/skills/land-pr/scripts/gh-host.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/land-pr/scripts/gh-host.sh"
fi

Step 2 — Resume-mode short-circuit (--pr <num>)

If $PR_RESUME is set, skip rebase / push / create — the caller has already done those and wants to monitor an existing PR. Set PR_NUMBER=$PR_RESUME and jump to step 6 (monitor).

Use case for --pr <num>: caller previously invoked /land-pr --no-monitor (or had a monitor timeout); the PR exists and the branch is pushed; now the caller wants to monitor (or re-monitor) without re-running rebase/push/create.

if [ -n "${ZSH_VERSION:-}" ]; then setopt KSH_ARRAYS BASH_REMATCH SH_WORD_SPLIT 2>/dev/null || true; fi
if [ -n "$PR_RESUME" ]; then
  PR_NUMBER="$PR_RESUME"
  PR_EXISTING=true
  # Recover PR_URL via gh — single read, no jq binary, bash regex on JSON.
  PR_VIEW_JSON=$(gh pr view "$PR_NUMBER" --json url 2>/dev/null) || PR_VIEW_JSON=""
  if [[ "$PR_VIEW_JSON" =~ \"url\":[[:space:]]*\"([^\"]+)\" ]]; then
    PR_URL="${BASH_REMATCH[1]}"
  fi
  # Skip steps 3–4.
fi

(The 2>/dev/null here is acceptable on this single read because recovery to empty PR_URL is an explicit handled outcome — the result file's PR_URL just stays empty if gh pr view fails. Other fallible calls in this skill MUST capture stderr to a sidecar; this is the documented exception for the resume-mode metadata recovery.)

Step 3 — Rebase (skipped in resume mode)

Run pr-rebase.sh against the configured base branch. Parse its stdout for CONFLICT_FILES_LIST / REASON. Map the exit code:

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -z "$PR_RESUME" ]; then
  REBASE_STDOUT=$(bash "$ZSKILLS_SKILLS_ROOT/land-pr/scripts/pr-rebase.sh" \
    --branch "$BRANCH" --base "$BASE_BRANCH")
  REBASE_RC=$?

  while IFS='=' read -r KEY VALUE; do
    case "$KEY" in
      CONFLICT_FILES_LIST) CONFLICT_FILES_LIST="$VALUE" ;;
      REASON) REASON="$VALUE" ;;
    esac
  done <<<"$REBASE_STDOUT"

  if [ "$REBASE_RC" -eq 10 ]; then
    STATUS="rebase-conflict"
    # Jump to step 9 (compose .zskills/landed + result file).
  elif [ "$REBASE_RC" -eq 11 ]; then
    STATUS="rebase-failed"
    # Jump to step 9.
  elif [ "$REBASE_RC" -eq 14 ]; then
    STATUS="rebase-failed"
    # Issue #420: pr-rebase.sh exits 14 when CWD's HEAD != $BRANCH
    # (REASON=wrong-current-branch, the #397/#419 guard). Map to
    # rebase-failed so the orchestrator surfaces the classification
    # instead of falling through to STATUS="" and proceeding silently.
    # REASON is already captured to wrong-current-branch above.
    # Jump to step 9.
  elif [ "$REBASE_RC" -eq 16 ]; then
    STATUS="rebase-failed"
    # Issue #481: pr-rebase.sh exits 16 when the working tree has
    # uncommitted changes (REASON=dirty-working-tree). Pre-#481 the
    # dirty-tree case fell through to the generic exit-11 terminus,
    # surfacing as REASON=rebase-failed and indistinguishable from real
    # conflicts, network failures, or abort failures. Map to
    # rebase-failed (same terminus class) but preserve REASON=
    # dirty-working-tree so the orchestrator can tell users "commit or
    # stash first" instead of misdiagnosing as a real rebase failure.
    # Jump to step 9.
  fi
fi

If STATUS is set to rebase-conflict or rebase-failed, skip steps 4–7 and proceed to step 8/9.

Step 4 — Push and create-or-detect PR (skipped in resume mode)

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -z "$PR_RESUME" ] && [ -z "$STATUS" ]; then
  PUSH_STDOUT=$(bash "$ZSKILLS_SKILLS_ROOT/land-pr/scripts/pr-push-and-create.sh" \
    --branch "$BRANCH" --base "$BASE_BRANCH" \
    --title "$TITLE" --body-file "$BODY_FILE")
  PUSH_RC=$?

  while IFS='=' read -r KEY VALUE; do
    case "$KEY" in
      PR_EXISTING) PR_EXISTING="$VALUE" ;;
      PR_URL) PR_URL="$VALUE" ;;
      PR_NUMBER) PR_NUMBER="$VALUE" ;;
      CALL_ERROR_FILE) CALL_ERROR_FILE="$VALUE" ;;
    esac
  done <<<"$PUSH_STDOUT"

  case "$PUSH_RC" in
    0) : ;;  # success, fall through
    12) STATUS="push-failed" ;;
    13) STATUS="create-failed" ;;
    14) STATUS="create-failed"; REASON="invalid-pr-number" ;;
    *)  STATUS="create-failed"; REASON="push-create-rc-$PUSH_RC" ;;
  esac
fi

Step 5 — --no-monitor short-circuit

If $NO_MONITOR is true and PR creation succeeded, set STATUS=created CI_STATUS=not-monitored and jump to step 8.

Use case for --no-monitor: caller wants to report the PR URL mid-flight, or split the create-and-monitor flow across two cron-fired turns. None of the 4 callers in this plan use --no-monitor — it is reserved for future callers.

if [ -z "$STATUS" ] && [ "$NO_MONITOR" = "true" ]; then
  STATUS="created"
  CI_STATUS="not-monitored"
fi

Step 6 — Monitor CI

Past failure (PR #131, 2026-04-30) — DO NOT skip this step. The agent skipped Step 6 on PR #131, read the previous inline bash block as suggestion-prose, did one snapshot gh pr checks 131 showing pending, reported that in the summary, and exited. User discovered the midnight CI flake 20+ minutes later by manual polling. The polling logic now lives in scripts/pr-monitor.sh so it MUST be invoked explicitly — paraphrasing or substituting a single gh pr checks snapshot is a skill-step skip.

Issue #133 documents this past-failure preamble; the conformance assertion check land-pr "PR #131 past-failure preamble" (added in WI 3.4) verifies the wording survives.

If STATUS is unset (or created with CI_STATUS=not-monitored already set in step 5, in which case skip), run pr-monitor.sh:

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -z "$STATUS" ] || { [ "$STATUS" = "created" ] && [ "$CI_STATUS" != "not-monitored" ]; }; then
  CI_LOG_OUT="/tmp/land-pr-ci-log-$BRANCH_SLUG-$$.txt"
  MONITOR_STDOUT=$(bash "$ZSKILLS_SKILLS_ROOT/land-pr/scripts/pr-monitor.sh" \
    --pr "$PR_NUMBER" --timeout "$CI_TIMEOUT" --log-out "$CI_LOG_OUT")
  MONITOR_RC=$?

  while IFS='=' read -r KEY VALUE; do
    case "$KEY" in
      CI_STATUS) CI_STATUS="$VALUE" ;;
      CI_LOG_FILE) CI_LOG_FILE="$VALUE" ;;
    esac
  done <<<"$MONITOR_STDOUT"

  if [ "$MONITOR_RC" -ne 0 ]; then
    STATUS="monitor-failed"
    REASON="monitor-rc-$MONITOR_RC"
  else
    STATUS="monitored"
  fi
fi

Step 6b — Auto-rebase BEHIND PRs post-CI-green (Issue #266)

After Step 6 returns CI_STATUS=pass, the PR's mergeStateStatus may be BEHIND because origin/$BASE_BRANCH advanced while CI was running (a sibling PR landed). On repos with "Require branches to be up to date before merging" branch protection, GitHub's auto-merge waits indefinitely in this state — the auto-merge does NOT auto-rebase the branch. Without this step, the PR sits at OPEN/BEHIND until someone manually rebases and force-pushes.

This step closes that loop: detect BEHIND, rebase locally onto current origin/$BASE_BRANCH, force-push with lease, re-poll CI, re-check mergeStateStatus. Bounded at 3 iterations to avoid pathological churn when many PRs are landing rapidly.

Skip conditions (skip the whole Step 6b loop):

• $AUTO_FLAG != true — BEHIND recovery is only useful when the caller is running unattended. Without --auto, BEHIND is the caller's problem to resolve manually.
• $STATUS already set to a failure terminus (rebase-conflict, push-failed, create-failed, monitor-failed, rebase-failed, merge-failed) — Step 6b shouldn't run after upstream failures.
• $CI_STATUS != pass — only act on green CI (avoid spinning on a permanently-failing PR).
• $PR_NUMBER empty — nothing to rebase against.

mergeStateStatus handling (the loop is keyed off this):

• CLEAN / HAS_HOOKS / UNSTABLE → mergeable, break loop, proceed to Step 7.
• BEHIND → fire the rebase + force-push + re-poll iteration.
• BLOCKED → branch protection blocking (e.g., review required); break loop with STATUS=auto-rebase-blocked REASON=mergeStateStatus-BLOCKED.
• CONFLICTING → genuine GitHub-side merge conflict; break loop with STATUS=auto-rebase-blocked REASON=mergeStateStatus-CONFLICTING.
• UNKNOWN → break loop with STATUS=auto-rebase-blocked REASON=auto-rebase-unknown.

Iteration cap is hardcoded 3. If exhausted still BEHIND, set STATUS=behind-thrash REASON=auto-rebase-exhausted, skip Step 7 (merge), proceed to Step 8 where the status mapping table maps behind-thrash → pr-ready (the PR is real and reviewable; the auto-rebase loop just gave up).

All rebase/push/fetch stderr is captured to a single sidecar /tmp/land-pr-auto-rebase-stderr-$BRANCH_SLUG-$$.log, referenced via REBASE_STDERR_FILE in the result file when the loop fails.

if [ -n "${ZSH_VERSION:-}" ]; then setopt KSH_ARRAYS BASH_REMATCH SH_WORD_SPLIT 2>/dev/null || true; fi
if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -z "$STATUS" ] \
   && [ "$AUTO_FLAG" = "true" ] \
   && [ "$CI_STATUS" = "pass" ] \
   && [ -n "$PR_NUMBER" ]; then
  REBASE_STDERR="/tmp/land-pr-auto-rebase-stderr-$BRANCH_SLUG-$$.log"
  : > "$REBASE_STDERR"
  AUTO_REBASE_ITER=0
  AUTO_REBASE_MAX=3

  # Initial mergeStateStatus probe.
  MS_JSON=$(gh pr view "$PR_NUMBER" --json mergeStateStatus 2>>"$REBASE_STDERR")
  MS_STATE=""
  if [[ "$MS_JSON" =~ \"mergeStateStatus\":[[:space:]]*\"([^\"]+)\" ]]; then
    MS_STATE="${BASH_REMATCH[1]}"
  fi

  # Resolve a transient UNKNOWN before deciding the loop. Right after a push,
  # GitHub hasn't finished computing mergeability and returns UNKNOWN (or, on
  # a slow read, empty). If we keyed the BEHIND loop off that raw value the
  # loop would never enter and Step 6b would silently no-op on a PR that is
  # actually BEHIND (observed live on PR #856). Bounded re-poll: up to 5
  # attempts ~3-4s apart until MS_STATE is a definite value. NEVER infinite.
  UNKNOWN_POLL=0
  UNKNOWN_POLL_MAX=5
  while { [ "$MS_STATE" = "UNKNOWN" ] || [ -z "$MS_STATE" ]; } \
        && [ "$UNKNOWN_POLL" -lt "$UNKNOWN_POLL_MAX" ]; do
    UNKNOWN_POLL=$((UNKNOWN_POLL + 1))
    echo "INFO: /land-pr Step 6b: mergeStateStatus=UNKNOWN (poll $UNKNOWN_POLL/$UNKNOWN_POLL_MAX); re-probing" >&2
    sleep 4
    MS_JSON=$(gh pr view "$PR_NUMBER" --json mergeStateStatus 2>>"$REBASE_STDERR")
    MS_STATE=""
    if [[ "$MS_JSON" =~ \"mergeStateStatus\":[[:space:]]*\"([^\"]+)\" ]]; then
      MS_STATE="${BASH_REMATCH[1]}"
    fi
  done

  while [ "$MS_STATE" = "BEHIND" ] && [ "$AUTO_REBASE_ITER" -lt "$AUTO_REBASE_MAX" ]; do
    AUTO_REBASE_ITER=$((AUTO_REBASE_ITER + 1))
    echo "INFO: /land-pr Step 6b: PR #$PR_NUMBER is BEHIND (iter $AUTO_REBASE_ITER/$AUTO_REBASE_MAX); rebasing + force-pushing" >&2

    # Rebase onto current origin/$BASE_BRANCH. Use WORKTREE_PATH when
    # provided; otherwise operate against current working dir.
    REBASE_DIR="${WORKTREE_PATH:-$(pwd)}"
    if ! git -C "$REBASE_DIR" fetch origin "$BASE_BRANCH" 2>>"$REBASE_STDERR"; then
      STATUS="auto-rebase-conflict"
      REASON="auto-rebase-fetch-failed-rc$?"
      break
    fi
    if ! git -C "$REBASE_DIR" rebase "origin/$BASE_BRANCH" 2>>"$REBASE_STDERR"; then
      # Rebase conflict — capture conflict files, abort, surface.
      CONFLICT_PATHS=$(git -C "$REBASE_DIR" diff --name-only --diff-filter=U 2>>"$REBASE_STDERR" | tr '\n' ' ' | sed 's/ $//')
      git -C "$REBASE_DIR" rebase --abort 2>>"$REBASE_STDERR" || true
      if [ -n "$CONFLICT_PATHS" ]; then
        CONFLICT_FILES_SIDECAR="/tmp/land-pr-auto-rebase-conflicts-$BRANCH_SLUG-$$.list"
        printf '%s\n' $CONFLICT_PATHS > "$CONFLICT_FILES_SIDECAR"
        CONFLICT_FILES_LIST="$CONFLICT_FILES_SIDECAR"
      fi
      STATUS="auto-rebase-conflict"
      REASON="auto-rebase-conflict-iter$AUTO_REBASE_ITER"
      break
    fi

    # Force-push with lease.
    if ! git -C "$REBASE_DIR" push --force-with-lease origin "$BRANCH" 2>>"$REBASE_STDERR"; then
      PUSH_RC=$?
      # On non-final iterations, retry: fetch+rebase loop top will pick
      # up any new origin moves. On final iteration, surface failure.
      if [ "$AUTO_REBASE_ITER" -ge "$AUTO_REBASE_MAX" ]; then
        STATUS="auto-rebase-blocked"
        REASON="auto-rebase-push-failed-rc$PUSH_RC"
        break
      fi
      echo "WARN: /land-pr Step 6b: push --force-with-lease failed (rc=$PUSH_RC); retrying" >&2
      # Refresh mergeStateStatus and continue loop.
      MS_JSON=$(gh pr view "$PR_NUMBER" --json mergeStateStatus 2>>"$REBASE_STDERR")
      MS_STATE=""
      if [[ "$MS_JSON" =~ \"mergeStateStatus\":[[:space:]]*\"([^\"]+)\" ]]; then
        MS_STATE="${BASH_REMATCH[1]}"
      fi
      continue
    fi

    # Re-poll CI on the rebased commit.
    CI_LOG_OUT="/tmp/land-pr-ci-log-$BRANCH_SLUG-rebase$AUTO_REBASE_ITER-$$.txt"
    MONITOR_STDOUT=$(bash "$ZSKILLS_SKILLS_ROOT/land-pr/scripts/pr-monitor.sh" \
      --pr "$PR_NUMBER" --timeout "$CI_TIMEOUT" --log-out "$CI_LOG_OUT")
    MONITOR_RC=$?
    while IFS='=' read -r KEY VALUE; do
      case "$KEY" in
        CI_STATUS) CI_STATUS="$VALUE" ;;
        CI_LOG_FILE) CI_LOG_FILE="$VALUE" ;;
      esac
    done <<<"$MONITOR_STDOUT"
    if [ "$MONITOR_RC" -ne 0 ] || [ "$CI_STATUS" != "pass" ]; then
      # CI failed (or monitor failed) on the rebased commit. Don't keep
      # spinning the rebase loop — surface and let the caller's fix-cycle
      # take over.
      STATUS="auto-rebase-blocked"
      REASON="auto-rebase-ci-${CI_STATUS:-monitor-failed}-iter$AUTO_REBASE_ITER"
      break
    fi

    # Re-check mergeStateStatus.
    MS_JSON=$(gh pr view "$PR_NUMBER" --json mergeStateStatus 2>>"$REBASE_STDERR")
    MS_STATE=""
    if [[ "$MS_JSON" =~ \"mergeStateStatus\":[[:space:]]*\"([^\"]+)\" ]]; then
      MS_STATE="${BASH_REMATCH[1]}"
    fi

    case "$MS_STATE" in
      CLEAN|HAS_HOOKS|UNSTABLE)
        echo "INFO: /land-pr Step 6b: mergeStateStatus=$MS_STATE after rebase (iter $AUTO_REBASE_ITER); proceeding to merge" >&2
        break
        ;;
      BEHIND)
        # Loop continues.
        ;;
      BLOCKED|CONFLICTING)
        STATUS="auto-rebase-blocked"
        REASON="mergeStateStatus-$MS_STATE"
        break
        ;;
      UNKNOWN|"")
        STATUS="auto-rebase-blocked"
        REASON="auto-rebase-unknown"
        break
        ;;
      *)
        STATUS="auto-rebase-blocked"
        REASON="mergeStateStatus-$MS_STATE"
        break
        ;;
    esac
  done

  # Loop exhausted still BEHIND → behind-thrash.
  if [ -z "$STATUS" ] && [ "$MS_STATE" = "BEHIND" ] && [ "$AUTO_REBASE_ITER" -ge "$AUTO_REBASE_MAX" ]; then
    STATUS="behind-thrash"
    REASON="auto-rebase-exhausted"
  fi

  # Reference the sidecar in the result file if the loop failed.
  if [ -s "$REBASE_STDERR" ] \
     && { [ "$STATUS" = "behind-thrash" ] \
          || [ "$STATUS" = "auto-rebase-conflict" ] \
          || [ "$STATUS" = "auto-rebase-blocked" ]; }; then
    REBASE_STDERR_FILE="$REBASE_STDERR"
  else
    rm -f "$REBASE_STDERR"
  fi
fi

Step 7 — Merge (gated on --automerge)

Always run pr-merge.sh — it owns the automerge/CI gating internally.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -n "$PR_NUMBER" ] && [ "$STATUS" != "rebase-conflict" ] && [ "$STATUS" != "rebase-failed" ] && [ "$STATUS" != "push-failed" ] && [ "$STATUS" != "create-failed" ] && [ "$STATUS" != "behind-thrash" ] && [ "$STATUS" != "auto-rebase-conflict" ] && [ "$STATUS" != "auto-rebase-blocked" ]; then
  MERGE_STDOUT=$(bash "$ZSKILLS_SKILLS_ROOT/land-pr/scripts/pr-merge.sh" \
    --pr "$PR_NUMBER" --automerge-flag "$AUTOMERGE_FLAG" --ci-status "${CI_STATUS:-not-monitored}")
  MERGE_RC=$?

  while IFS='=' read -r KEY VALUE; do
    case "$KEY" in
      MERGE_REQUESTED) MERGE_REQUESTED="$VALUE" ;;
      MERGE_REASON) MERGE_REASON="$VALUE" ;;
      PR_STATE) PR_STATE="$VALUE" ;;
      CALL_ERROR_FILE) CALL_ERROR_FILE="$VALUE" ;;
    esac
  done <<<"$MERGE_STDOUT"

  if [ "$MERGE_RC" -eq 30 ]; then
    STATUS="merge-failed"
    REASON="${REASON:-merge-rc-30}"
  elif [ "$MERGE_REQUESTED" = "true" ] && [ "$PR_STATE" = "MERGED" ]; then
    STATUS="merged"
  fi
fi

Step 7d — Drive a queued auto-merge to a terminal state (Issue #871)

Step 7 requests GitHub auto-merge and returns. When the merge request succeeds but the PR is still OPEN (auto-merge queued, waiting on branch protection), nothing in the old flow looped back. If a sibling PR lands after the merge request, our PR goes OPEN/BEHIND; on "Require branches to be up to date before merging" repos GitHub's queued auto-merge then waits indefinitely — the auto-merge never auto-rebases. Step 6b only handles BEHIND that exists before the merge request; this step handles BEHIND that appears after it. Observed live on PR #856.

This step drives the queued auto-merge to a terminus by clearing any post-request BEHIND (re-using the exact Step 6b rebase machinery) and re-checking, bounded by both a wall-clock timeout and a max iteration count so it can NEVER hang. It does NOT re-request auto-merge — pr-merge.sh already queued it; re-requesting is redundant. We only rebase to clear BEHIND and let the already-queued auto-merge fire.

Run conditions (ALL must hold; otherwise skip entirely):

• $AUTO_FLAG = true — only meaningful when auto-merge was requested.
• $MERGE_REQUESTED = true — the merge was actually queued.
• $PR_STATE = OPEN — already MERGED needs no driving; UNKNOWN/other isn't a queued-and-waiting state.
• $NO_MONITOR = false AND $PR_RESUME empty — --no-monitor and --pr resume mode are explicitly exempt (same exemptions Step 6/6b honor; these modes hand monitoring back to the caller).
• $STATUS is merged only would short-circuit (it's already terminal); and $STATUS must NOT be a failure terminus (merge-failed, auto-rebase-blocked, auto-rebase-conflict, behind-thrash, monitor-failed, etc.) — those are already surfaced.

Per-iteration handling of gh pr view --json state,mergeStateStatus:

• state=MERGED → set PR_STATE=MERGED STATUS=merged, done. (Step 7b/7c below then fire their post-merge fast-forward + tracking copy.)
• mergeStateStatus=BEHIND → re-enter the SAME Step 6b rebase + force-push-with-lease + re-monitor + re-check sequence. Do NOT duplicate-diverge: the inline block below calls the identical git fetch → git rebase → git push --force-with-lease → pr-monitor.sh → re-probe steps Step 6b uses. The queued auto-merge fires once BEHIND clears.
• mergeStateStatus in CLEAN|HAS_HOOKS|UNSTABLE → mergeable; the queued auto-merge should fire imminently — keep waiting (re-poll) until MERGED or timeout.
• BLOCKED|CONFLICTING → STATUS=auto-rebase-blocked REASON=mergeStateStatus-<state>, surface, break.
• UNKNOWN/empty → bounded re-poll (same shape as the Step 6b UNKNOWN resolver above), never treated as terminal.
• Timeout OR max-iterations exhausted while still OPEN → leave STATUS unchanged (monitored) and set REASON=auto-merge-wait-timeout, so Step 8 maps it to pr-ready (row 7) with an explicit reason — NEVER silent.

The loop is bounded by $CI_TIMEOUT seconds of wall-clock AND a hard iteration cap (10). Per-iteration sleep is ~15s between polls. The rebase sub-path itself is bounded by the same AUTO_REBASE_MAX=3 cap Step 6b uses, so the total work is finite.

if [ -n "${ZSH_VERSION:-}" ]; then setopt KSH_ARRAYS BASH_REMATCH SH_WORD_SPLIT 2>/dev/null || true; fi
if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ "$AUTO_FLAG" = "true" ] \
   && [ "$MERGE_REQUESTED" = "true" ] \
   && [ "$PR_STATE" = "OPEN" ] \
   && [ "$NO_MONITOR" = "false" ] \
   && [ -z "$PR_RESUME" ] \
   && [ "$STATUS" != "merge-failed" ] \
   && [ "$STATUS" != "auto-rebase-blocked" ] \
   && [ "$STATUS" != "auto-rebase-conflict" ] \
   && [ "$STATUS" != "behind-thrash" ] \
   && [ "$STATUS" != "monitor-failed" ]; then
  TW_STDERR="/tmp/land-pr-terminal-wait-stderr-$BRANCH_SLUG-$$.log"
  : > "$TW_STDERR"
  TW_DEADLINE=$(( $(date +%s) + CI_TIMEOUT ))
  TW_ITER=0
  TW_ITER_MAX=10

  while [ "$TW_ITER" -lt "$TW_ITER_MAX" ] && [ "$(date +%s)" -lt "$TW_DEADLINE" ]; do
    TW_ITER=$((TW_ITER + 1))

    # Poll state + mergeStateStatus together.
    TW_JSON=$(gh pr view "$PR_NUMBER" --json state,mergeStateStatus 2>>"$TW_STDERR")
    TW_PR_STATE=""
    TW_MS_STATE=""
    if [[ "$TW_JSON" =~ \"state\":[[:space:]]*\"([^\"]+)\" ]]; then
      TW_PR_STATE="${BASH_REMATCH[1]}"
    fi
    if [[ "$TW_JSON" =~ \"mergeStateStatus\":[[:space:]]*\"([^\"]+)\" ]]; then
      TW_MS_STATE="${BASH_REMATCH[1]}"
    fi

    # Terminal: the queued auto-merge fired.
    if [ "$TW_PR_STATE" = "MERGED" ]; then
      PR_STATE="MERGED"
      STATUS="merged"
      echo "INFO: /land-pr Step 7d: PR #$PR_NUMBER reached MERGED (iter $TW_ITER)" >&2
      break
    fi

    # Resolve a transient UNKNOWN before acting (same bounded shape as 6b).
    TW_UNKNOWN_POLL=0
    while { [ "$TW_MS_STATE" = "UNKNOWN" ] || [ -z "$TW_MS_STATE" ]; } \
          && [ "$TW_UNKNOWN_POLL" -lt 5 ]; do
      TW_UNKNOWN_POLL=$((TW_UNKNOWN_POLL + 1))
      sleep 4
      TW_JSON=$(gh pr view "$PR_NUMBER" --json state,mergeStateStatus 2>>"$TW_STDERR")
      TW_PR_STATE=""
      TW_MS_STATE=""
      if [[ "$TW_JSON" =~ \"state\":[[:space:]]*\"([^\"]+)\" ]]; then
        TW_PR_STATE="${BASH_REMATCH[1]}"
      fi
      if [[ "$TW_JSON" =~ \"mergeStateStatus\":[[:space:]]*\"([^\"]+)\" ]]; then
        TW_MS_STATE="${BASH_REMATCH[1]}"
      fi
    done
    if [ "$TW_PR_STATE" = "MERGED" ]; then
      PR_STATE="MERGED"
      STATUS="merged"
      break
    fi

    case "$TW_MS_STATE" in
      BEHIND)
        # Re-enter the EXACT Step 6b rebase machinery to clear BEHIND. We
        # do NOT re-request auto-merge — the queued auto-merge fires once
        # BEHIND clears. Bounded by AUTO_REBASE_MAX (3), same as Step 6b.
        echo "INFO: /land-pr Step 7d: PR #$PR_NUMBER went BEHIND post-merge-request (iter $TW_ITER); rebasing" >&2
        TW_REBASE_ITER=0
        TW_REBASE_MAX=3
        TW_REBASE_OK=false
        while [ "$TW_REBASE_ITER" -lt "$TW_REBASE_MAX" ]; do
          TW_REBASE_ITER=$((TW_REBASE_ITER + 1))
          REBASE_DIR="${WORKTREE_PATH:-$(pwd)}"
          if ! git -C "$REBASE_DIR" fetch origin "$BASE_BRANCH" 2>>"$TW_STDERR"; then
            STATUS="auto-rebase-conflict"
            REASON="auto-rebase-fetch-failed-rc$?"
            break
          fi
          if ! git -C "$REBASE_DIR" rebase "origin/$BASE_BRANCH" 2>>"$TW_STDERR"; then
            CONFLICT_PATHS=$(git -C "$REBASE_DIR" diff --name-only --diff-filter=U 2>>"$TW_STDERR" | tr '\n' ' ' | sed 's/ $//')
            git -C "$REBASE_DIR" rebase --abort 2>>"$TW_STDERR" || true
            if [ -n "$CONFLICT_PATHS" ]; then
              CONFLICT_FILES_SIDECAR="/tmp/land-pr-terminal-wait-conflicts-$BRANCH_SLUG-$$.list"
              printf '%s\n' $CONFLICT_PATHS > "$CONFLICT_FILES_SIDECAR"
              CONFLICT_FILES_LIST="$CONFLICT_FILES_SIDECAR"
            fi
            STATUS="auto-rebase-conflict"
            REASON="auto-rebase-conflict-tw-iter$TW_REBASE_ITER"
            break
          fi
          if ! git -C "$REBASE_DIR" push --force-with-lease origin "$BRANCH" 2>>"$TW_STDERR"; then
            PUSH_RC=$?
            if [ "$TW_REBASE_ITER" -ge "$TW_REBASE_MAX" ]; then
              STATUS="auto-rebase-blocked"
              REASON="auto-rebase-push-failed-rc$PUSH_RC"
              break
            fi
            echo "WARN: /land-pr Step 7d: push --force-with-lease failed (rc=$PUSH_RC); retrying" >&2
            continue
          fi
          # Re-monitor CI on the rebased commit (identical to Step 6b).
          CI_LOG_OUT="/tmp/land-pr-ci-log-$BRANCH_SLUG-tw$TW_REBASE_ITER-$$.txt"
          MONITOR_STDOUT=$(bash "$ZSKILLS_SKILLS_ROOT/land-pr/scripts/pr-monitor.sh" \
            --pr "$PR_NUMBER" --timeout "$CI_TIMEOUT" --log-out "$CI_LOG_OUT")
          MONITOR_RC=$?
          while IFS='=' read -r KEY VALUE; do
            case "$KEY" in
              CI_STATUS) CI_STATUS="$VALUE" ;;
              CI_LOG_FILE) CI_LOG_FILE="$VALUE" ;;
            esac
          done <<<"$MONITOR_STDOUT"
          if [ "$MONITOR_RC" -ne 0 ] || [ "$CI_STATUS" != "pass" ]; then
            STATUS="auto-rebase-blocked"
            REASON="auto-rebase-ci-${CI_STATUS:-monitor-failed}-tw-iter$TW_REBASE_ITER"
            break
          fi
          TW_REBASE_OK=true
          break
        done
        if [ "$TW_REBASE_OK" != "true" ]; then
          # A failure terminus was set above (or push exhausted) — surface
          # and break the outer wait. Step 8 maps these (auto-rebase-*) to
          # pr-ready/conflict.
          if [ -z "$STATUS" ] || [ "$STATUS" = "monitored" ] || [ "$STATUS" = "merged" ]; then
            STATUS="behind-thrash"
            REASON="${REASON:-auto-rebase-exhausted-tw}"
          fi
          break
        fi
        # Rebase cleared BEHIND; loop back and let the queued auto-merge fire.
        ;;
      CLEAN|HAS_HOOKS|UNSTABLE)
        # Mergeable and queued — wait for the auto-merge to fire.
        echo "INFO: /land-pr Step 7d: PR #$PR_NUMBER mergeStateStatus=$TW_MS_STATE; waiting for queued auto-merge (iter $TW_ITER)" >&2
        ;;
      BLOCKED|CONFLICTING)
        STATUS="auto-rebase-blocked"
        REASON="mergeStateStatus-$TW_MS_STATE"
        echo "WARN: /land-pr Step 7d: PR #$PR_NUMBER mergeStateStatus=$TW_MS_STATE; surfacing" >&2
        break
        ;;
      *)
        # Unexpected definite state — surface, don't spin.
        STATUS="auto-rebase-blocked"
        REASON="mergeStateStatus-${TW_MS_STATE:-empty}"
        break
        ;;
    esac

    sleep 15
  done

  # Bounded-out while still OPEN → leave STATUS=monitored, explicit REASON,
  # Step 8 maps to pr-ready (row 7). NEVER silent.
  if [ "$PR_STATE" = "OPEN" ] \
     && [ "$STATUS" != "auto-rebase-blocked" ] \
     && [ "$STATUS" != "auto-rebase-conflict" ] \
     && [ "$STATUS" != "behind-thrash" ] \
     && [ "$STATUS" != "merged" ]; then
    REASON="${REASON:-auto-merge-wait-timeout}"
    echo "WARN: /land-pr Step 7d: auto-merge did not reach a terminus within ${CI_TIMEOUT}s / ${TW_ITER_MAX} iterations; PR #$PR_NUMBER left OPEN (REASON=$REASON)" >&2
  fi

  if [ -s "$TW_STDERR" ] \
     && { [ "$STATUS" = "auto-rebase-blocked" ] \
          || [ "$STATUS" = "auto-rebase-conflict" ] \
          || [ "$STATUS" = "behind-thrash" ]; }; then
    REBASE_STDERR_FILE="${REBASE_STDERR_FILE:-$TW_STDERR}"
  else
    rm -f "$TW_STDERR"
  fi
fi

Step 7b — Fast-forward local main after successful merge

When pr-merge.sh confirmed PR_STATE=MERGED, refresh local $BASE_BRANCH so subsequent worktree creations and any consumer of main see ground truth. Without this step, local main's ref + working tree stay at the pre-merge SHA after a squash-merge, and downstream skills anchor on stale ground state. Issue #254. Failure modes are surfaced loud — never silent — and never destructive (mirrors the fetch+ff-merge+ahead-check discipline from create-worktree.sh:268-291, landed via #225 / PR #232).

if [ "$MERGE_REQUESTED" = "true" ] && [ "$PR_STATE" = "MERGED" ]; then
  MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)/.." && pwd)
  if [ -z "$MAIN_ROOT" ] || { [ ! -d "$MAIN_ROOT/.git" ] && [ ! -f "$MAIN_ROOT/.git" ]; }; then
    echo "WARN: /land-pr Step 7b: could not resolve MAIN_ROOT; skipping local-main FF" >&2
  else
    MAIN_HEAD_REF=$(git -C "$MAIN_ROOT" symbolic-ref --short HEAD 2>/dev/null || echo "")
    MAIN_DIRTY=""
    if [ -n "$MAIN_HEAD_REF" ]; then
      MAIN_DIRTY=$(git -C "$MAIN_ROOT" status --porcelain 2>/dev/null | head -1)
    fi
    AHEAD=$(git -C "$MAIN_ROOT" rev-list --count "origin/$BASE_BRANCH..$BASE_BRANCH" 2>/dev/null || echo "0")

    if [ "$MAIN_HEAD_REF" != "$BASE_BRANCH" ]; then
      echo "INFO: /land-pr Step 7b: MAIN_ROOT not on $BASE_BRANCH (HEAD=$MAIN_HEAD_REF); skipping local-main FF" >&2
    elif [ -n "$MAIN_DIRTY" ]; then
      echo "WARN: /land-pr Step 7b: MAIN_ROOT working tree dirty; skipping local-main FF" >&2
    elif [ "$AHEAD" -gt 0 ]; then
      echo "WARN: /land-pr Step 7b: local $BASE_BRANCH is $AHEAD commit(s) ahead of origin — refusing FF" >&2
    else
      FF_STDERR="/tmp/land-pr-ff-stderr-$BRANCH_SLUG-$$.log"
      if git -C "$MAIN_ROOT" fetch origin "$BASE_BRANCH" 2>"$FF_STDERR" \
         && git -C "$MAIN_ROOT" merge --ff-only "origin/$BASE_BRANCH" 2>>"$FF_STDERR"; then
        echo "INFO: /land-pr Step 7b: fast-forwarded local $BASE_BRANCH to origin/$BASE_BRANCH"
        rm -f "$FF_STDERR"
      else
        echo "WARN: /land-pr Step 7b: fetch+ff-merge failed (see $FF_STDERR); local $BASE_BRANCH not updated" >&2
      fi
    fi
  fi
fi

Step 7c — Copy worktree tracking markers to main (Issue #604)

/run-plan PR mode writes its per-phase step.run-plan.<id>.{implement,verify,report} markers to the worktree's .zskills/tracking/$PIPELINE_ID/ subdir, which is gitignored and disappears when the worktree is removed post-merge. That leaves main's tracking subdir with at most step.*.implement (somehow) and step.*.land — the .verify companion that the enforce_step_verify_marker hook gate consults is missing its .report peer, and subsequent phases' commits get blocked (Issue #604). Fix: after a successful squash-merge, copy the worktree's entire pipeline subdir (step.*, requires.*, fulfilled.*) into main. Discipline mirrors Step 7b — loud failure (WARN: …), never silent, never destructive. cp -af is last-run-wins per issue body's edge-case guidance.

if [ "$MERGE_REQUESTED" = "true" ] && [ "$PR_STATE" = "MERGED" ] && [ -n "$WORKTREE_PATH" ]; then
  COPY_PIPELINE_ID="${ZSKILLS_PIPELINE_ID:-${TRACKING_ID:+run-plan.$TRACKING_ID}}"
  COPY_MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)/.." && pwd)
  if [ -z "$COPY_PIPELINE_ID" ]; then
    echo "INFO: /land-pr Step 7c: no PIPELINE_ID resolvable (no --tracking-id and no ZSKILLS_PIPELINE_ID); skipping tracking copy"
  elif [ -z "$COPY_MAIN_ROOT" ] || { [ ! -d "$COPY_MAIN_ROOT/.git" ] && [ ! -f "$COPY_MAIN_ROOT/.git" ]; }; then
    echo "WARN: /land-pr Step 7c: could not resolve MAIN_ROOT; skipping tracking copy" >&2
  else
    WT_TRACK="$WORKTREE_PATH/.zskills/tracking/$COPY_PIPELINE_ID"
    MAIN_TRACK="$COPY_MAIN_ROOT/.zskills/tracking/$COPY_PIPELINE_ID"
    if [ -d "$WT_TRACK" ]; then
      mkdir -p "$MAIN_TRACK"
      CP_STDERR="/tmp/land-pr-tracking-copy-stderr-$BRANCH_SLUG-$$.log"
      if cp -af "$WT_TRACK/." "$MAIN_TRACK/" 2>"$CP_STDERR"; then
        echo "INFO: /land-pr Step 7c: copied $WT_TRACK/. → $MAIN_TRACK/ (last-run-wins)"
        rm -f "$CP_STDERR"
      else
        echo "WARN: /land-pr Step 7c: cp -af failed (see $CP_STDERR); tracking markers not fully copied" >&2
      fi
    else
      echo "INFO: /land-pr Step 7c: no worktree tracking subdir at $WT_TRACK; skipping copy"
    fi
  fi
fi

Step 8 — Compose .zskills/landed (auto-detect worktree if --worktree-path omitted)

Use this status mapping table to derive .zskills/landed's status field. Evaluation: top-down, first-match-wins. Failure-exits and pre-conditions come first; CI_STATUS=fail and CI_STATUS=pending take precedence over MERGE_REQUESTED/PR_STATE rows because the merge-requested-but-CI-failed combo (auto-merge accepted but CI changed after) should NOT be reported as landed.

#	Condition (top-down, first match wins)	→ .zskills/landed status
1	STATUS=rebase-conflict	conflict
1b	STATUS=auto-rebase-conflict	conflict
2	STATUS in {push-failed, create-failed, rebase-failed, merge-failed, monitor-failed}	pr-failed
2b	STATUS=behind-thrash	pr-ready
2c	STATUS=auto-rebase-blocked	pr-ready
3	CI_STATUS=fail	pr-ci-failing
4	CI_STATUS=pending	pr-ready
5	CI_STATUS=unknown	pr-ready
6	MERGE_REQUESTED=true AND PR_STATE=MERGED AND CI_STATUS in {pass, none, skipped}	landed
7	MERGE_REQUESTED=true AND PR_STATE=OPEN AND CI_STATUS in {pass, none, skipped}	pr-ready
8	MERGE_REQUESTED=true AND PR_STATE=UNKNOWN AND CI_STATUS in {pass, none, skipped}	pr-state-unknown
9	MERGE_REQUESTED=false (auto-merge-disabled-on-repo) AND CI_STATUS in {pass, none, skipped}	pr-ready
10	MERGE_REQUESTED=false (auto-not-requested) AND CI_STATUS in {pass, none, skipped}	pr-ready

Compose the body and pipe to write-landed.sh. When --worktree-path is omitted, auto-detect from cwd: if cwd is a registered linked worktree of the current repo (NOT the main worktree, which has no associated branch-of-work to mark), use it as the marker target. This closes the Issue #205 gap where orchestrator-direct /land-pr dispatch from inside a worktree but without --worktree-path silently skipped the .zskills/landed write. --worktree-path remains an explicit override.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
# Auto-detect WORKTREE_PATH from cwd when caller didn't pass --worktree-path.
# Detection uses `git rev-parse` (worktree root + git-dir vs git-common-dir
# divergence indicates a LINKED worktree, not the main worktree) plus
# membership in `git worktree list --porcelain` for defense-in-depth.
if [ -z "$WORKTREE_PATH" ]; then
  CANDIDATE=$(git rev-parse --show-toplevel 2>/dev/null) || CANDIDATE=""
  if [ -n "$CANDIDATE" ]; then
    GIT_DIR=$(git -C "$CANDIDATE" rev-parse --git-dir 2>/dev/null) || GIT_DIR=""
    GIT_COMMON_DIR=$(git -C "$CANDIDATE" rev-parse --git-common-dir 2>/dev/null) || GIT_COMMON_DIR=""
    # Linked worktree: per-worktree git-dir differs from common-dir.
    # Main worktree (or non-worktree dir): they match (or are empty on failure).
    if [ -n "$GIT_DIR" ] && [ -n "$GIT_COMMON_DIR" ] && [ "$GIT_DIR" != "$GIT_COMMON_DIR" ]; then
      # Verify membership in `git worktree list` to guard against odd
      # checkout layouts that happen to expose distinct git-dirs.
      if git -C "$CANDIDATE" worktree list --porcelain 2>/dev/null | grep -qF "worktree $CANDIDATE"; then
        WORKTREE_PATH="$CANDIDATE"
      fi
    fi
  fi
fi

if [ -n "$WORKTREE_PATH" ]; then
  # Derive .zskills/landed status from the table above.
  LANDED_STATUS="pr-ready"  # default fallback
  case "$STATUS" in
    rebase-conflict|auto-rebase-conflict) LANDED_STATUS="conflict" ;;
    push-failed|create-failed|rebase-failed|merge-failed|monitor-failed)
      LANDED_STATUS="pr-failed" ;;
    behind-thrash|auto-rebase-blocked) LANDED_STATUS="pr-ready" ;;
    *)
      case "$CI_STATUS" in
        fail) LANDED_STATUS="pr-ci-failing" ;;
        pending|unknown) LANDED_STATUS="pr-ready" ;;
        pass|none|skipped|not-monitored)
          if [ "$MERGE_REQUESTED" = "true" ]; then
            case "$PR_STATE" in
              MERGED) LANDED_STATUS="landed" ;;
              OPEN) LANDED_STATUS="pr-ready" ;;
              UNKNOWN) LANDED_STATUS="pr-state-unknown" ;;
              *) LANDED_STATUS="pr-ready" ;;
            esac
          else
            LANDED_STATUS="pr-ready"
          fi
          ;;
      esac
      ;;
  esac

  # Metadata-only capture; on rare git failures (detached HEAD with
  # missing origin/$BASE_BRANCH ref) COMMITS_LIST stays empty rather than
  # aborting .zskills/landed write. Stderr goes to a discarded log, not the
  # null device — keeps the file inspectable post-mortem.
  #
  # Use `origin/$BASE_BRANCH` (NOT local `$BASE_BRANCH`): in multi-PR
  # sequential sprints, local main goes stale relative to origin/main
  # after each auto-merge, which over-populates this list with squash
  # commits from prior sprints' PRs (Issue #203). pr-rebase.sh fetches
  # origin/$BASE_BRANCH earlier in the pipeline, so it's always current
  # by the time we reach Step 8.
  GIT_LOG_STDERR="/tmp/land-pr-commits-list-stderr-$BRANCH_SLUG-$$.log"
  COMMITS_LIST=$(cd "$WORKTREE_PATH" && git log --format=%H "origin/$BASE_BRANCH..HEAD" 2>"$GIT_LOG_STDERR" | tr '\n' ' ' | sed 's/ $//')
  LANDED_DATE=$(TZ="${TIMEZONE:-UTC}" date -Iseconds)

  {
    printf 'status: %s\n' "$LANDED_STATUS"
    printf 'date: %s\n'   "$LANDED_DATE"
    printf 'source: %s\n' "$LANDED_SOURCE"
    printf 'method: pr\n'
    printf 'branch: %s\n' "$BRANCH"
    [ -n "$PR_URL" ]         && printf 'pr: %s\n'        "$PR_URL"
    [ -n "$CI_STATUS" ]      && printf 'ci: %s\n'        "$CI_STATUS"
    [ "$PR_STATE" != "not-checked" ] && printf 'pr_state: %s\n' "$PR_STATE"
    [ -n "$COMMITS_LIST" ]   && printf 'commits: %s\n'   "$COMMITS_LIST"
    [ -n "$ISSUE_NUM" ]      && printf 'issue: %s\n'     "$ISSUE_NUM"
    [ -n "$REASON" ]         && printf 'reason: %s\n'    "$REASON"
  } | bash "$ZSKILLS_SKILLS_ROOT/commit/scripts/write-landed.sh" "$WORKTREE_PATH"
fi

Step 8b — Write fulfilled.land-pr.<id> (only when --tracking-id given AND row-6 merge gate holds)

Write the fulfillment marker ONLY when the caller passed --tracking-id AND the PR is actually merged on main. Match the row-6 gate from Step 8's .zskills/landed status-mapping table:

MERGE_REQUESTED=true AND PR_STATE=MERGED AND CI_STATUS in {pass, none, skipped}

Any other state (pr-ready, pr-ci-failing, push-failed, rebase-conflict, pr-state-unknown, etc.) means the work isn't actually landed — do NOT fulfill. The 3 non-/run-plan callers never pass --tracking-id, so this block is a no-op for them (preserves current behavior exactly).

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
if [ -n "$TRACKING_ID" ] \
   && [ "$MERGE_REQUESTED" = "true" ] \
   && [ "$PR_STATE" = "MERGED" ] \
   && { [ "$CI_STATUS" = "pass" ] || [ "$CI_STATUS" = "none" ] || [ "$CI_STATUS" = "skipped" ]; }; then
  PIPELINE_ID="${ZSKILLS_PIPELINE_ID:-run-plan.$TRACKING_ID}"
  MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)/.." && pwd)
  PIPELINE_SUBDIR="$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID"
  if [ -d "$PIPELINE_SUBDIR" ]; then
    printf 'skill: land-pr\nid: %s\npr: %s\nbranch: %s\ndate: %s\n' \
      "$TRACKING_ID" "$PR_URL" "$BRANCH" "$(TZ="${TIMEZONE:-UTC}" date -Iseconds)" \
      > "$PIPELINE_SUBDIR/fulfilled.land-pr.$TRACKING_ID"
  fi
fi

Step 9 — Write the result file (atomic; allow-list parser will read it)

Default any unset values to the empty string, then validate every value before writing. Atomic write via .tmp + mv.

# Defaults for unset values.
: "${STATUS:=monitored}"
: "${PR_URL:=}"
: "${PR_NUMBER:=}"
: "${PR_EXISTING:=false}"
: "${CI_STATUS:=not-monitored}"
: "${CI_LOG_FILE:=}"
: "${MERGE_REQUESTED:=false}"
: "${MERGE_REASON:=empty}"
: "${PR_STATE:=not-checked}"
: "${REASON:=}"
: "${CONFLICT_FILES_LIST:=}"
: "${CALL_ERROR_FILE:=}"
: "${REBASE_STDERR_FILE:=}"

TMP_RESULT="$RESULT_FILE.tmp"
: > "$TMP_RESULT"

write_kv() {
  local key="$1" value="$2"
  validate_result_value "$key" "$value" || return 1
  printf '%s=%s\n' "$key" "$value" >> "$TMP_RESULT"
}

write_kv STATUS              "$STATUS"              || exit 40
write_kv PR_URL              "$PR_URL"              || exit 40
write_kv PR_NUMBER           "$PR_NUMBER"           || exit 40
write_kv PR_EXISTING         "$PR_EXISTING"         || exit 40
write_kv CI_STATUS           "$CI_STATUS"           || exit 40
write_kv CI_LOG_FILE         "$CI_LOG_FILE"         || exit 40
write_kv MERGE_REQUESTED     "$MERGE_REQUESTED"     || exit 40
write_kv MERGE_REASON        "$MERGE_REASON"        || exit 40
write_kv PR_STATE            "$PR_STATE"            || exit 40
write_kv REASON              "$REASON"              || exit 40
write_kv CONFLICT_FILES_LIST "$CONFLICT_FILES_LIST" || exit 40
write_kv CALL_ERROR_FILE     "$CALL_ERROR_FILE"     || exit 40
write_kv REBASE_STDERR_FILE  "$REBASE_STDERR_FILE"  || exit 40

mv "$TMP_RESULT" "$RESULT_FILE"

Step 10 — One-line summary to stdout

echo "STATUS=$STATUS PR=${PR_URL:-(none)} CI=${CI_STATUS:-(none)}"

Idempotency contract

/land-pr is idempotent per call — re-invoking with the same branch is a no-op for steps already done:

• pr-rebase.sh: git rebase origin/<base> is a no-op when the local branch is already on top of the base. Exit 0.
• pr-push-and-create.sh: git push with no new commits is a no-op (gh's "Everything up-to-date" message). gh pr list detects an existing PR; we emit PR_EXISTING=true and exit 0 without calling gh pr create again. The script does NOT call gh pr edit --body-file on the existing-PR path — body update is the caller's responsibility.
• pr-monitor.sh: stateless — re-running after a pending outcome resumes polling the same PR cleanly.
• pr-merge.sh: gh pr merge --auto is idempotent (re-requesting auto-merge on a PR that already has it queued is a no-op).

The fix-cycle re-invocation case (caller pushed a fix commit, /land-pr is called again) does NOT cause spurious conflicts: the local branch's new commits are already rebased on origin/main from the prior pass.

Cross-skill dispatch contract

• Skill-tool dispatch, single-string args. Per skills/research-and-plan/SKILL.md:140, callers invoke /land-pr via Skill: { skill: "land-pr", args: "<flags>" }. Same-context recursion per skills/research-and-plan/SKILL.md:87-105. Therefore data hand-off is file-based (the result file), not via stdout.
• No jq binary. gh ... --json is gh's built-in formatter; we bash-regex its output. The standalone jq binary is prohibited per the feedback_no_jq_in_skills memory.
• No || true, no 2>/dev/null on fallible operations (with one documented exception: the --pr resume-mode metadata recovery in step 2, which is an explicit handled outcome).
• No --no-verify on commits.