Land

Goals

• Ensure the PR is conflict-free with main.

• Keep CI green and fix failures when they occur.

• Squash-merge the PR once checks pass.

• Do not yield to the user until the PR is merged; keep the watcher loop running unless blocked.

• No need to delete remote branches after merge; the repo auto-deletes head branches.

Preconditions

• gh CLI is authenticated.

• You are on the PR branch with a clean working tree.

Steps

• Locate the PR for the current branch.

• Confirm the full gauntlet is green locally before any push.

• If the working tree has uncommitted changes, commit with the commit skill and push with the push skill before proceeding.

• Check mergeability and conflicts against main.

• If conflicts exist, use the pull skill to fetch/merge origin/main and resolve conflicts, then use the push skill to publish the updated branch.

• Ensure Codex review comments (if present) are acknowledged and any required fixes are handled before merging.

• Watch checks until complete.

• If checks fail, pull logs, fix the issue, commit with the commit skill, push with the push skill, and re-run checks.

• When all checks are green and review feedback is addressed, squash-merge and delete the branch using the PR title/body for the merge subject/body.

• Context guard: Before implementing review feedback, confirm it does not conflict with the user’s stated intent or task context. If it conflicts, respond inline with a justification and ask the user before changing code.

• Pushback template: When disagreeing, reply inline with: acknowledge + rationale + offer alternative.

• Ambiguity gate: When ambiguity blocks progress, use the clarification flow (assign PR to current GH user, mention them, wait for response). Do not implement until ambiguity is resolved.

• If you are confident you know better than the reviewer, you may proceed without asking the user, but reply inline with your rationale.

• Per-comment mode: For each review comment, choose one of: accept, clarify, or push back. Reply inline (or in the issue thread for Codex reviews) stating the mode before changing code.

• Reply before change: Always respond with intended action before pushing code changes (inline for review comments, issue thread for Codex reviews).

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).