docs: wave PRs — drop/release wait for a closed wave PR, settle's base checks, more QUEUE_WAVE_* cases

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

docs/ship-policy.md

@@ -488,8 +488,8 @@ gstack-ship-queue wave settle --wave <nonce> [--dry-run]        # after the wave
 - **Frozen heads.** Once in, a constituent's head does not move. Fixes go on
   the wave branch as integrator commits, which the chain check allows. A
   constituent that has to change goes back to its owner: `--drop <pr>` builds
-  a new wave on a new branch (never a force-push; the old record is marked
-  superseded and its PR is closed by the integrator), refused with
+  a new wave on a new branch (never a force-push; the integrator closes the
+  old wave PR first, and the old record is marked superseded), refused with
   `QUEUE_WAVE_DEPENDENT` when another pin contains the dropped one. A drop
   that would leave fewer PRs than the minimum releases the wave instead, and
   `--release` does the same for a wave PR closed without merging: the record
@@ -510,12 +510,13 @@ gstack-ship-queue wave settle --wave <nonce> [--dry-run]        # after the wave
   land`, `verify`, the stamp and the backstop treat it like any PR, and under
   `changelog_fragments` its one stamp folds every constituent's fragment into
   one version section.
-- **After the merge.** `wave settle` finds the merged wave PR, checks main's
-  merge carries its head tree and walks its chain (the train's stamp commit on
-  top is allowed). A constituent still at its pin gets a "Landed in wave #W as
-  vX (sha)" comment naming any integrator commits that touched its files, and
-  is closed. One whose head moved after the wave froze stays open with a
-  comment saying its newer work did not land. Comments carry a marker, so a
+- **After the merge.** `wave settle` finds the wave PR merged into the base
+  branch, checks that its merge commit is on that branch and carries its head
+  tree, and walks its chain (train land's stamp commits on top are allowed). A
+  constituent still at its pin gets a "Landed in wave #W as vX (sha)" comment
+  naming any integrator commits or hand-resolved merges that touched its
+  files, and is closed. One whose head moved after the wave froze stays open
+  with a comment saying its newer work did not land. Comments carry a marker, so a
   rerun posts nothing twice; `--dry-run` shows the plan.
 
 <a id="ship-before-ready"></a>

docs/troubleshooting.md

@@ -4758,23 +4758,29 @@ build the wave without that PR.
 pushed, closed or merged after it joined (heads freeze once in), the wave
 branch carries a merge that is not a constituent's pin (main merged in, for
 example), a pin is missing from the branch, or the wave was rebuilt and this
-PR is the old one.
+PR is the old one. The same code refuses a constituent that targets a branch
+other than the base (a stacked PR's pin carries its parent's commits), a
+wave that was released, and a `--drop` or `--release` while the wave PR is
+still open, since a train that already admitted it would still land it.
 
-**Fix.** Rebuild without the moved PR, `wave build --wave <nonce> --drop
-<pr>`, which makes a new wave branch and PR (never a force-push); run /ship
-and READY the new wave PR. The moved PR goes back to its owner and rides on its
-own or in a later wave.
+**Fix.** Close the wave PR if one is open, then rebuild without the moved PR,
+`wave build --wave <nonce> --drop <pr>`, which makes a new wave branch and PR (never a
+force-push); run /ship and READY the new wave PR. The moved PR goes back to
+its owner and rides on its own or in a later wave. A stacked PR rides on its
+own; after a release, each constituent is READY'd on its own.
 
 <a id="queue-wave-duplicate"></a>
 ### `QUEUE_WAVE_DUPLICATE`
 
 **Meaning.** A PR would land twice or waves would nest: it is already a
 constituent of another live wave, `train build` was handed both a wave PR and
-one of its constituents (or two waves sharing one), or a wave PR was named as a
-constituent.
+one of its constituents (or two waves sharing one), a wave PR was named as a
+constituent, or a constituent of a live wave was READY'd or handed to `train
+build` on its own.
 
 **Fix.** Keep each PR in one place: drop the separate pin from `train build`,
-or rebuild one wave without the shared PR.
+or rebuild one wave without the shared PR. A constituent of a live wave lands
+through the wave PR.
 
 <a id="queue-wave-size"></a>
 ### `QUEUE_WAVE_SIZE`
@@ -4808,9 +4814,10 @@ still land the dropped code.
 <a id="queue-wave-not-merged"></a>
 ### `QUEUE_WAVE_NOT_MERGED`
 
-**Meaning.** `wave settle` found no merged PR whose head branch is the wave
-branch, or main's merge commit does not carry that PR's head tree, so it
-cannot say the constituents landed. Nothing was commented or closed.
+**Meaning.** `wave settle` found no PR merged into the base branch whose head
+branch is the wave branch, its merge commit is not on the base branch, or that
+merge does not carry the PR's head tree, so it cannot say the constituents
+landed. Nothing was commented or closed.
 
 **Fix.** Land the wave PR through its train (`train land`), then rerun
 `gstack-ship-queue wave settle --wave <nonce>`.