From 89d173c036fd34e456df496f303c94c04edca758 Mon Sep 17 00:00:00 2001 From: garrytan Date: Tue, 27 Oct 2026 12:20:38 +0000 Subject: [PATCH] docs: stamp rule for tentative key versions, key=value prose claims, QUEUE_STALE merged-not-in-base fix Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/pregate.md | 4 +++- docs/ship-policy.md | 15 ++++++++++++--- docs/troubleshooting.md | 6 +++++- 3 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/pregate.md b/docs/pregate.md index 80f72bd3d..a1bf4619e 100644 --- a/docs/pregate.md +++ b/docs/pregate.md @@ -456,7 +456,9 @@ receipt for H when the two trees differ only as a stamp does: that does not account for every path `git diff-tree` lists between the two trees. The version rule is the tree receipt's: a `stamp_files`, `stamp_paths` or `release_outputs` hunk is a stamp - only as the rewrite from the gated tree's version to the head's (so two trees + only as the rewrite to the head's version from the gated tree's version, or + from a newer tentative version of the repo's width that the stamp moved (a + `*_KEY_VERSION` written as the next minor, #3512) (so two trees at the same version refuse such a hunk as `other`), while the built-in version-file, manifest, lockfile and CHANGELOG rules compare content and do not check the direction of the version move. The obligation stays uncleared; rerun diff --git a/docs/ship-policy.md b/docs/ship-policy.md index d97b43c56..afdf218e6 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -725,7 +725,9 @@ integers under `review_loop`, `gate` and `ci`: `passes=2`, `passes: 2` and several counters, `passed` under `gate` and `ci` or `pass` under every gate lane, matches when the number equals any of them; an underscore in a key matches `_`, a space or `-`; a name inside a longer word, `3 pass-through`, is -not a claim). A body that quotes a different number is +not a claim; a number that is the value of a `key=` or `key:` pair is that +key's claim alone, so `passes=2 blocking_found=1` is two claims, never a +`2 blocking_found` one, #3513). A body that quotes a different number is `RECEIPT_PROSE_MISMATCH` (exit 1) and the `PROSE:` line names each field with both values; prose that quotes no counter is not a claim. Data PRs (evals, measurements, sweeps) run it before READY so the body's numbers are the run's. @@ -815,7 +817,11 @@ dependency, a script or a new key makes them product). A path the policy's `stamp_files`, `stamp_paths` or `release_outputs` name is metadata only while its change is a stamp, the rule the tree receipt applies to the same paths: a manifest by its version key, any other file when its new text reads as the old -once the new release version is replaced by the old one. A logic change in a +once the new release version is replaced by the old one, or when every changed +line is a stamp-form rewrite to the new version of the old version or of a +newer tentative one the stamp moved (a `*_KEY_VERSION` written as the next +minor, #3512; a version older than the old one or of another width is a hand +edit). A logic change in a stamped source file is product. Lockfiles are product unless the policy names them. A base merge contributes no product change of its own. A receipt carried twice keeps the reviewed head as @@ -957,7 +963,10 @@ only, where `gstack-version-bump` writes; a dependency entry is `changed`), the CHANGELOG (a heading move or re-heading, compared as an order-independent multiset of entries), `stamp_paths` and `release_outputs` (every removed/added pair must be an exact `(was X)` / `since: X` / `vX` rewrite (a quote around X in the first two forms included) with -X the gated version and the replacement the current one, so a dependency pin +X the gated version, or a newer version of the repo's width that the +stamp_paths stage moves (a tentative `*_KEY_VERSION` written as the next +minor, #3512; a version older than the gated one, or of another width, is a +hand edit), and the replacement the current one, so a dependency pin that happens to equal the old version is `changed`; `stamp_patterns` templates count as stamp forms too). With `stamp_files` set, a file outside it is `changed (stamp_files: not in the repo's stamp_files allowlist)` whatever diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 17fab7ddb..04255e7bb 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2716,7 +2716,11 @@ and the message says so. The JSON result carries `expected`, `actual` and **Fix.** Run the printed `recompute` command: it carries the corrected order (this PR first, merged PRs dropped, an unmerged predecessor kept ahead because it must merge first) and recomputes the version from the current base; then -merge with the server-side head condition (`MERGE_CONDITION: sha=`). +merge with the server-side head condition (`MERGE_CONDITION: sha=`). A +predecessor GitHub calls merged that the local base does not carry yet +(`#=merged-not-in-base`) is kept ahead too, with `fix: git fetch origin +`: fetch, then rerun, so the recompute, pinned to that local base, never +allocates the version the predecessor already took. ### `RESTAMP_VERSION_SOURCE`