From 12759e0b18f2f829e506286e63b3f0bb422f4f38 Mon Sep 17 00:00:00 2001 From: garrytan Date: Thu, 29 Oct 2026 01:40:24 +0000 Subject: [PATCH] docs: troubleshooting names the stacked-retarget carry refusals Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/troubleshooting.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3bb588677..e59cf3aeb 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4698,14 +4698,18 @@ to HEAD: the PR body has no valid receipt, the working tree has uncommitted or untracked changes (a carry certifies a commit, never a tree that differs from it), the receipt's head left HEAD's history and the receipt records no tree to compare (a receipt written before `head_tree`, whose head is not in this -clone), or git could not compare the two product diffs or read the working -tree's status. The receipt in the body is unchanged and still names the old -head, so `gstack-ship-queue ready` refuses `QUEUE_RECEIPT_STALE`. +clone), the PR was retargeted to the base after its stack parent landed but +the receipt records no `product_patch_id` and `origin/` no longer +resolves, so the reviewed range cannot be recomputed, or git could not +compare the two product diffs or read the working tree's status. The receipt +in the body is unchanged and still names the old head, so +`gstack-ship-queue ready` refuses `QUEUE_RECEIPT_STALE`. **Fix.** Commit or stash every working-tree change, then rerun `gstack-ship-receipt carry --pr ` at the new head. When the history is already rewritten and the receipt predates `head_tree`, run /ship on the new -head; next time merge the base in instead of rebasing. +head; next time merge the base in instead of rebasing. For a retargeted stacked +PR whose older receipt lost its parent branch, run /ship on the new head. ### `RECEIPT_CARRY_TREE_MISMATCH` @@ -4734,12 +4738,14 @@ is not the reviewed one. For a stacked PR retargeted to the base after its parent landed, it means HEAD's product diff against the base is not the range reviewed against the parent branch: the parent has not fully landed, or the branch changed since. The reviewed verdict does not cover HEAD, so the -receipt is not carried. The refusal names the changed product paths. +receipt is not carried. The refusal names the changed product paths, or for a +retargeted stacked PR the parent branch and the base. **Fix.** Run /ship on the new head. The receipt carries only across a conflict-only base merge, a test-only change, release metadata, a registered -output the pregate's regen check proved, or a rebase onto a covered tree with -the recorded product diff, which the +output the pregate's regen check proved, a rebase onto a covered tree with +the recorded product diff, or a stacked PR's retarget once its parent fully +landed on the base, which the `carry` object in the carried receipt records with the product patch-id and the range-diff evidence ([unattended.md](unattended.md#the-terminal-line)).