From b06ccf3ec2a43510b7824c82ea24f4a1c3b69dcb Mon Sep 17 00:00:00 2001 From: garrytan Date: Sun, 1 Nov 2026 11:40:16 +0000 Subject: [PATCH] docs: wave plan grouping, NOT_GREEN and unreadable CI in ship-policy; changelog fragment (GST-770) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- changelog.d/gst-wave-plan-hub-files.md | 1 + docs/ship-policy.md | 13 ++++++++----- 2 files changed, 9 insertions(+), 5 deletions(-) create mode 100644 changelog.d/gst-wave-plan-hub-files.md diff --git a/changelog.d/gst-wave-plan-hub-files.md b/changelog.d/gst-wave-plan-hub-files.md new file mode 100644 index 000000000..2d4635e82 --- /dev/null +++ b/changelog.d/gst-wave-plan-hub-files.md @@ -0,0 +1 @@ +- `gstack-ship-queue wave plan` no longer packs the whole READY queue into one area. Two PRs now share a wave only when `git merge-tree` finds a real conflict between them in a code file or skill template. Docs, other Markdown and JSON ledgers never link PRs, since most PRs add to them. Before, any shared file linked two PRs, so `docs/troubleshooting.md` and a few ledgers chained 55 READY PRs into eight waves all labeled `setup`. With this change the same queue gives five groups by area. A READY head whose CI is red or still running now prints `NOT_GREEN: # (...)` and stays out of the plan, as `ready` would refuse it. A head whose CI cannot be read fails the plan with `QUEUE_PROOF_MISSING`, the same as an unreadable PR. Renamed files are compared by their real paths (GST-770). diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 53bcc2496..040da5794 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -573,14 +573,17 @@ gstack-ship-queue wave settle --wave [--dry-run] # after the wave ``` - **When.** `wave plan` counts the live READY PRs (open, head equal to their - READY receipt, CI green at that head; a READY head whose CI is red or still - running prints a `NOT_GREEN` line and stays out of the plan). Over the + READY receipt, CI green at that head; a READY head whose CI is red, still + running or absent prints a `NOT_GREEN` line and stays out of the plan). A + READY PR whose CI, head or diff cannot be read fails the whole plan with + `QUEUE_PROOF_MISSING`. Over the trigger (6) it prints `WAVE_ADVISED` and suggested groups of 3 to 6: PRs whose changes to a common code file conflict (`git merge-tree` cannot merge - the two heads) always share a group, so that conflict is resolved once. Hub + the two heads, or the check itself fails) always share a group, so that + conflict is resolved once. Hub files never link PRs: anything under `docs/`, Markdown (generated skill - renders included; their `.tmpl` sources still link) and JSON ledgers and - registries. Most PRs append to them, and + renders included; their `.tmpl` sources still link) and every `.json` or + `.jsonl` file (ledgers and registries). Most PRs append to them, and linking through them once chained a 55-PR queue into a single area (GST-770). Each group takes its largest PR's functional area (a skill directory, the first word of a `lib/`, `bin/` or `test/`