From 72c296ba605e1f41ee6d2cf5b37c1da914fff0ca Mon Sep 17 00:00:00 2001 From: garrytan Date: Sat, 31 Oct 2026 19:41:47 +0000 Subject: [PATCH] docs: describe the default-base skip when origin/HEAD names the branch (GST-511) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/eval-calls.md | 3 ++- docs/eval-models.md | 3 ++- docs/troubleshooting.md | 19 +++++++++++++++++-- 3 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/eval-calls.md b/docs/eval-calls.md index fb7f9101e..176a589f5 100644 --- a/docs/eval-calls.md +++ b/docs/eval-calls.md @@ -22,7 +22,8 @@ dropped), so a command with quotes or `$` never passes through a shell string; 1. `--plan-file `: an operator-given file, read from disk. 2. Otherwise `price_file` in `.gstack/pregate.json` as committed on - `origin/` (`--base`, default origin/HEAD's branch): a repo-relative + `origin/` (`--base`, default origin/HEAD's branch unless that is the + checked-out branch, then the PR's base, `main` or `master`): a repo-relative path whose bytes are read from the **HEAD commit** (`git show HEAD:`), never from the working tree. diff --git a/docs/eval-models.md b/docs/eval-models.md index 406149101..eabefb8e2 100644 --- a/docs/eval-models.md +++ b/docs/eval-models.md @@ -66,7 +66,8 @@ unless the command says it is a smoke run. ## Which copy is read By default the reviewed copy is read: `git show origin/:.gstack/eval-models.json` -(`--base`, default origin/HEAD's branch). A branch cannot loosen the rules it +(`--base`, default origin/HEAD's branch unless that is the checked-out branch, +then the PR's base, `main` or `master`). A branch cannot loosen the rules it is checked against. When the working-tree copy differs, an `EVAL_MODELS_NOTE:` line says so. `--models-from head` lints with the working-tree copy instead. Use it for the PR that adds or changes the file; the source label diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1c0dcb22d..12a8a25bd 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2234,12 +2234,26 @@ base, because an empty diff against a wrong or absent base would read as "no gate edits" and pass review. `gstack-diff-scope` prints `SCOPE_ERROR=no_base` (all flags false, exit 2) for the same cause. +With no base given, one more cause applies. The remote's `HEAD` names the +branch you have checked out (a clone made by a PR flow can point `origin/HEAD` +at the PR branch, GST-511), and nothing past it resolves: no PR base from +`gh`, no `/main`, no `/master`. That base would diff the branch +against itself, so the line reads `GATE_ERROR=no_base ref=/HEAD +target=/ fix=git remote set-head `, +`gstack-diff-scope` adds a `#` line naming the branch, and the ship-policy +readers (`gstack-pregate`, `gstack-ship-receipt`, `gstack-ship-queue`, ...) +print `gstack: origin/HEAD names the checked-out branch , ...` on +stderr before refusing on a base that does not resolve. + **Fix.** Run the command the line prints. It is built for this checkout: `git fetch origin +:refs/remotes/origin/` for an unfetched branch, `git fetch --unshallow origin ` or `git fetch --deepen=50 origin` when the clone is shallow. In a workflow, check out with `fetch-depth: 0` (or fetch the base explicitly) before the step that -runs `gstack-gate-diff` or `gstack-diff-scope`. +runs `gstack-gate-diff` or `gstack-diff-scope`. When the remote's `HEAD` names +the checked-out branch, pass the base explicitly (`gstack-gate-diff `, +`gstack-diff-scope `, `--base `) or run +`git remote set-head origin `. **Expected result.** `gstack-gate-diff ` prints `GATE_SUMMARY:` and `gstack-diff-scope` prints its `SCOPE_*` flags without an error line. @@ -3530,7 +3544,8 @@ lane as stamp-sensitive (stamp_sensitive_gates: tests)` (the base policy says the test tier reads the stamps, as gstack's own does, so no run on another tree covers this one; rerun the gate on the head), `pregate.json was recorded against origin/, not this repository's base origin/` (rerun `gstack-pregate --base -`, or `git remote set-head origin ` when `origin/HEAD` was unset), and +`, or `git remote set-head origin ` when `origin/HEAD` was unset or +named the checked-out branch), and `.gstack/ship-policy.json on origin/@ is invalid` or `could not be read` (fix the policy on the base, or fetch it).