docs(ship-policy): tentative key versions are clear of main's pace; the receipt accepts the move only at the base version until #3512

Pass-1 review notes: the next patch above the fork point is the number main
takes first, so the convention names the next minor; and the tree receipt's
stamp-only check (lib/tree-receipt.ts stampOnlyHunks, with stampOnlyText and
stampFreeTree) rewrites only base VERSION -> new VERSION, so a tentative move
passes the train only when the tentative value equals the base version at the
slot. Filed as #3512 (outside this diff, deferred under the frozen scope).

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

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## [Unreleased]
 
 ### Changed
-- **Policy key versions are stamped, not hand-moved** (`lib/ship-policy.ts`, `.gstack/ship-policy.json`): `DOCS_CAPS_KEY_VERSION` is 1.91.270.0, the release that shipped `docs.caps` (#3487 was written naming 1.91.258.0, which main stamped for another PR; a slot call never permits an edit beyond the four stamp files, so the constant could not move at the slot). gstack's own policy now lists `lib/ship-policy.ts` under `stamp_paths` with the `_KEY_VERSION = '{version}'` template in `stamp_patterns`: a new key's constant is written as a tentative future version (the next patch above the fork point) and `gstack-restamp`'s stamp_paths stage moves it to the allocated version at the slot stamp, reading the base branch's policy, so the stage is live for the PRs after this one. `test/gstack-ship-policy.test.ts` adds the check the incident lacked: a released key's version must be a CHANGELOG heading whose entry names the key, so a tentative value no stamp moved fails (keys from before `review_scope` are exempt).
+- **Policy key versions are stamped, not hand-moved** (`lib/ship-policy.ts`, `.gstack/ship-policy.json`): `DOCS_CAPS_KEY_VERSION` is 1.91.270.0, the release that shipped `docs.caps` (#3487 was written naming 1.91.258.0, which main stamped for another PR; a slot call never permits an edit beyond the four stamp files, so the constant could not move at the slot). gstack's own policy now lists `lib/ship-policy.ts` under `stamp_paths` with the `_KEY_VERSION = '{version}'` template in `stamp_patterns`: a new key's constant is written as a tentative future version clear of main's pace (the next minor) and `gstack-restamp`'s stamp_paths stage moves it to the allocated version at the slot stamp, reading the base branch's policy, so the stage is live for the PRs after this one; the tree receipt's stamp-only check still accepts that move only when the tentative value equals the base version at the slot (#3512). `test/gstack-ship-policy.test.ts` adds the check the incident lacked: a released key's version must be a CHANGELOG heading whose entry names the key, so a tentative value no stamp moved fails (keys from before `review_scope` are exempt).
 
 ## [1.91.270.0] - 2026-10-27
 

lib/ship-policy.ts

@@ -162,14 +162,17 @@ export const TRAIN_KEYS_VERSION = '1.91.146.0';
 // Each constant is the release that first reads its key: a policy declaring the key must name at least
 // that version as min_gstack_version, so an older gstack refuses the policy by name instead of failing on
 // an unknown key. review_scope shipped in 1.91.256.0 (#3481), docs.caps in 1.91.270.0 (#3487). A new key's
-// constant is written as a tentative future version (the next patch after the fork point, in this exact
-// `_KEY_VERSION = '<version>'` form): this file is in .gstack/ship-policy.json stamp_paths with that form as a
+// constant is written as a tentative future version clear of main's pace (the next minor, never the next patch,
+// which main takes first and the released-key test below then reds at the pin), in this exact
+// `_KEY_VERSION = '<version>'` form: this file is in .gstack/ship-policy.json stamp_paths with that form as a
 // stamp_patterns template, so the slot stamp's gstack-restamp stamp_paths stage moves the tentative value to the
 // allocated version. The stage reads lines the branch added: a tentative value newer than the fork version moves,
 // an untouched released constant stays, and a branch-added line naming the base's own version is re-read as a
-// stale stamp and moves too, so never rewrite a released constant's line. test/gstack-ship-policy.test.ts holds an
-// unreleased constant newer than every CHANGELOG heading and a released one on a heading whose entry names its
-// key, so a value a stamp did not move fails there.
+// stale stamp and moves too, so never rewrite a released constant's line. Until the tree receipt accepts a
+// stamp-form move whose old value is not the base version (#3512), the train's stamp-only check passes such a
+// move only when the tentative value equals the base version at the slot. test/gstack-ship-policy.test.ts holds
+// an unreleased constant newer than every CHANGELOG heading and a released one on a heading whose entry names
+// its key, so a value a stamp did not move fails there.
 export const REVIEW_SCOPE_KEY_VERSION = '1.91.256.0';
 export const DOCS_CAPS_KEY_VERSION = '1.91.270.0';
 export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {