Land

Commands

# Ensure branch and PR context
branch=$(git branch --show-current)
pr_number=$(gh pr view --json number -q .number)
pr_title=$(gh pr view --json title -q .title)
pr_body=$(gh pr view --json body -q .body)

# Check mergeability and conflicts
mergeable=$(gh pr view --json mergeable -q .mergeable)

if [ "$mergeable" = "CONFLICTING" ]; then
  # Run the `pull` skill to handle fetch + merge + conflict resolution.
  # Then run the `push` skill to publish the updated branch.
fi

# Preferred: use the Async Watch Helper below. The manual loop is a fallback
# when Python cannot run or the helper script is unavailable.
# Wait for review feedback: Codex reviews arrive as issue comments that start
# with "## Codex Review — <persona>". Treat them like reviewer feedback: reply
# with a `[codex]` issue comment acknowledging the findings and whether you're
# addressing or deferring them.
while true; do
  gh api repos/{owner}/{repo}/issues/"$pr_number"/comments \
    --jq '.[] | select(.body | startswith("## Codex Review")) | .id' | rg -q '.' \
    && break
  sleep 10
done

# Watch checks
if ! gh pr checks --watch; then
  gh pr checks
  # Identify failing run and inspect logs
  # gh run list --branch "$branch"
  # gh run view <run-id> --log
  exit 1
fi

# Squash-merge (remote branches auto-delete on merge in this repo)
gh pr merge --squash --subject "$pr_title" --body "$pr_body"

Async Watch Helper

Preferred: use the asyncio watcher to monitor review comments, CI, and head updates in parallel:

python3 .codex/skills/land/land_watch.py

Exit codes:

• 2: Review comments detected (address feedback)
• 3: CI checks failed
• 4: PR head updated (autofix commit detected)

Failure Handling

• If checks fail, pull details with gh pr checks and gh run view --log, then fix locally, commit with the commit skill, push with the push skill, and re-run the watch.
• Use judgment to identify flaky failures. If a failure is a flake (e.g., a timeout on only one platform), you may proceed without fixing it.
• If CI pushes an auto-fix commit (authored by GitHub Actions), it does not trigger a fresh CI run. Detect the updated PR head, pull locally, merge origin/main if needed, add a real author commit, and force-push to retrigger CI, then restart the checks loop.
• If all jobs fail with corrupted pnpm lockfile errors on the merge commit, the remediation is to fetch latest origin/main, merge, force-push, and rerun CI.
• If mergeability is UNKNOWN, wait and re-check.
• Do not merge while review comments (human or Codex review) are outstanding.
• Codex review jobs retry on failure and are non-blocking; use the presence of ## Codex Review — <persona> issue comments (not job status) as the signal that review feedback is available.
• Do not enable auto-merge; this repo has no required checks so auto-merge can skip tests.
• If the remote PR branch advanced due to your own prior force-push or merge, avoid redundant merges; re-run the formatter locally if needed and git push --force-with-lease.

Review Handling

• Codex reviews now arrive as issue comments posted by GitHub Actions. They start with ## Codex Review — <persona> and include the reviewer’s methodology + guardrails used. Treat these as feedback that must be acknowledged before merge.
• Human review comments are blocking and must be addressed (responded to and resolved) before requesting a new review or merging.
• If multiple reviewers comment in the same thread, respond to each comment (batching is fine) before closing the thread.
• Fetch review comments via gh api and reply with a prefixed comment.
• Use review comment endpoints (not issue comments) to find inline feedback:
  • List PR review comments:

    gh api repos/{owner}/{repo}/pulls/<pr_number>/comments
    

  • PR issue comments (top-level discussion):

    gh api repos/{owner}/{repo}/issues/<pr_number>/comments
    

  • Reply to a specific review comment:

    gh api -X POST /repos/{owner}/{repo}/pulls/<pr_number>/comments \
      -f body='[codex] <response>' -F in_reply_to=<comment_id>
    

• in_reply_to must be the numeric review comment id (e.g., 2710521800), not the GraphQL node id (e.g., PRRC_...), and the endpoint must include the PR number (/pulls/<pr_number>/comments).
• If GraphQL review reply mutation is forbidden, use REST.
• A 404 on reply typically means the wrong endpoint (missing PR number) or insufficient scope; verify by listing comments first.
• All GitHub comments generated by this agent must be prefixed with [codex].
• For Codex review issue comments, reply in the issue thread (not a review thread) with [codex] and state whether you will address the feedback now or defer it (include rationale).
• If feedback requires changes:
  • For inline review comments (human), reply with intended fixes ([codex] ...) as an inline reply to the original review comment using the review comment endpoint and in_reply_to (do not use issue comments for this).
  • Implement fixes, commit, push.
  • Reply with the fix details and commit sha ([codex] ...) in the same place you acknowledged the feedback (issue comment for Codex reviews, inline reply for review comments).
  • The land watcher treats Codex review issue comments as unresolved until a newer [codex] issue comment is posted acknowledging the findings.
• Only request a new Codex review when you need a rerun (e.g., after new commits). Do not request one without changes since the last review.
  • Before requesting a new Codex review, re-run the land watcher and ensure there are zero outstanding review comments (all have [codex] inline replies).
  • After pushing new commits, the Codex review workflow will rerun on PR synchronization (or you can re-run the workflow manually). Post a concise root-level summary comment so reviewers have the latest delta:

    [codex] Changes since last review:
    - <short bullets of deltas>
    Commits: <sha>, <sha>
    Tests: <commands run>
    

  • Only request a new review if there is at least one new commit since the previous request.
  • Wait for the next Codex review comment before merging.

Scope + PR Metadata

• The PR title and description should reflect the full scope of the change, not just the most recent fix.
• If review feedback expands scope, decide whether to include it now or defer it. You can accept, defer, or decline feedback. If deferring or declining, call it out in the root-level [codex] update with a brief reason (e.g., out-of-scope, conflicts with intent, unnecessary).
• Correctness issues raised in review comments should be addressed. If you plan to defer or decline a correctness concern, validate first and explain why the concern does not apply.
• Classify each review comment as one of: correctness, design, style, clarification, scope.
• For correctness feedback, provide concrete validation (test, log, or reasoning) before closing it.
• When accepting feedback, include a one-line rationale in the root-level update.
• When declining feedback, offer a brief alternative or follow-up trigger.
• Prefer a single consolidated "review addressed" root-level comment after a batch of fixes instead of many small updates.
• For doc feedback, confirm the doc change matches behavior (no doc-only edits to appease review).