From 8f72d827c817bce937e5b24b91ca6be448e67df9 Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 26 Oct 2026 16:39:32 +0000 Subject: [PATCH] docs: RED screens are not seated; QUEUE_PROOF_MISSING and POLICY_SOURCE_UNAVAILABLE name the train-command causes Step 14.5 re-audit: ship-policy.md says train build does not seat a RED screen and its NEXT names the build without that PR; troubleshooting.md lists train forget, train watch, verify --screen and the scratch-branch push under QUEUE_PROOF_MISSING, and the origin/ fetch under POLICY_SOURCE_UNAVAILABLE. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/ship-policy.md | 3 ++- docs/troubleshooting.md | 13 ++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 3fb80cf1e..0f923c29c 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -605,7 +605,8 @@ prose, and record it in the READY receipt (`screen.verdict`): `SCREEN_VERDICT: no verdict (its report job did not finish): `ready --screen` dispatches afresh instead of following it, `verify --screen` refuses it (`QUEUE_PROOF_MISSING`) and `train build` seats the pin unscreened, as for `NOT-RUN`. A RED screen refuses `ready` under -either choice and is never re-dispatched at the same merge SHA +either choice, is never re-dispatched at the same merge SHA and is not seated +by `train build`, whose `NEXT:` names the build without that PR (`QUEUE_SCREEN_RED`); a run that concluded success with no slice (its route job found the head superseded or the plan selected nothing) is `NOT-RUN`: `verify --screen` refuses with `QUEUE_SCREEN_NOT_RUN`, `ready --screen` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 138f1b9db..0e412f5a1 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2503,7 +2503,9 @@ or corrupt object) that `git ls-tree` cannot confirm is absent; it never falls through to the user-owned file. It also refuses when Bun loaded a `.env` file from the working directory (a bare `bun gstack-pregate`), since a branch could then pick the user policy: run `gstack-pregate` directly or as -`bun --no-env-file`. +`bun --no-env-file`. `gstack-ship-queue ready` under a train policy fetches +`origin/` first and refuses with this code, quoting git's error, when +that fetch fails. **Fix.** `git fetch origin --depth=1`, then rerun. To run against the branch's own file deliberately, pass `--policy-from head --allow-repo-commands`; @@ -3834,8 +3836,13 @@ which line is not yet true. input does not match: the gated head is not a commit here, HEAD differs from the gated head beyond stamps (the gate never covered this tree), an earlier stamp with other inputs is unfinished, the stamp journal's head moved, or a -gate-ahead merge could not be recomputed with `git merge-tree`. Nothing was -written unless the `QUEUE_STAMP_REFUSED:` line says `committed=yes`. +gate-ahead merge could not be recomputed with `git merge-tree`. The train +commands use it too: `train forget` on a record that does not exist or on a +train still building, running or merging, `train watch` on an unknown record, +`verify --pr --screen` on a run with no verdict to read (an INCOMPLETE or +unreadable run), and `ready --screen` when the scratch merge branch cannot be +pushed. Nothing was written unless the `QUEUE_STAMP_REFUSED:` line says +`committed=yes`. **Fix.** Supply the named input (fetch the gated head, pass the current base sha), or regate the tree you mean to stamp. For an unfinished stamp, rerun the