From 54ecee2583db6dd3c98047eb43176733ec783b28 Mon Sep 17 00:00:00 2001 From: garrytan Date: Tue, 27 Oct 2026 08:41:59 +0000 Subject: [PATCH] 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 | 2 +- lib/ship-policy.ts | 13 ++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cad43744b..02bd216aa 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/lib/ship-policy.ts b/lib/ship-policy.ts index 62253edf5..5b1f0b803 100644 --- a/lib/ship-policy.ts +++ b/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 = ''` 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 = ''` 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 = {