[garrytan]

{
  "schema_version": 1,
  "pr": 3511,
  "head": "bad9f530461bb6b98763abb3f6bd0c5c50d4d9a6",
  "version": "1.91.270.0",
  "base": "main",
  "gate": {
    "remote_gate": {
      "pass": 11413,
      "fail": 0,
      "source": "gstack-pregate --stage tests --remote (Ubicloud, whole free tier) at tree 9735ffc163a6, $0.05; the same 11,413/0 at trees e45bc87f, 6bae99af and 11779f57 for the earlier heads"
    },
    "local_pregate": {
      "pass": 7,
      "fail": 0,
      "source": "gstack-pregate --allow-repo-commands at head bad9f530 (tree 9735ffc1): regen fresh, secrets, lanes; 7 checks, requires-remote only"
    },
    "typecheck": {
      "pass": 1,
      "fail": 0,
      "source": "bun run typecheck clean; typecheck:test none new (9f1a6b3, 2bb3f58); bad9f530 touches docs/ship-policy.md only"
    },
    "free-tests.yml": {
      "pass": 1,
      "fail": 0,
      "source": "pull_request run 40478524851 at bad9f530, success"
    },
    "windows-free-tests.yml": {
      "pass": 1,
      "fail": 0,
      "source": "pull_request run 40478522594 at bad9f530, success"
    },
    "docs_tests": {
      "pass": 49,
      "fail": 0,
      "source": "test/compare-pr-version.test.ts and test/ship-queue-train-logic.test.ts (the two tests naming docs/ship-policy.md) at bad9f530"
    },
    "pull_request_checks": {
      "pass": 45,
      "fail": 0,
      "source": "every pull_request check GitHub scheduled at bad9f530 (Free Tests, Windows Free Tests, Version Gate, Quality gate, E2E Evals, Skill Docs Freshness, Workflow Lint): 45 pass, 0 fail, 0 pending, 11 skipped (dispatch-only and train-only jobs); mergeStateStatus CLEAN"
    }
  },
  "session_kind": "unattended",
  "pregate": "requires-remote cleared @9735ffc163a6 (1 checks, current for bad9f530461b)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/40478524851",
    "windows-free-tests.yml/windows-free-shard: https://github.com/garrytan/gstack/actions/runs/40478522594",
    "pregate.json/remote_gate: remote-gate tree=9735ffc163a6 tests=11413"
  ],
  "issues": {
    "fixes": [],
    "refs": [
      3487,
      3512
    ],
    "flakes": []
  },
  "review_loop": {
    "passes": 4,
    "blocking_found": 1,
    "deferred": 1,
    "noted": 7,
    "fixed": 3,
    "scope": "frozen"
  }
}

Follow-up to #3487 (v1.91.270.0). DOCS_CAPS_KEY_VERSION was written as 1.91.258.0 and main stamped that number for another PR first; a slot stamp cannot edit anything beyond the four stamp files, so the constant shipped naming a release that never read docs. This PR corrects the value and makes the constant a stamp path so the next key does not repeat it.

Refs #3487
Refs #3512

Summary

• lib/ship-policy.ts: DOCS_CAPS_KEY_VERSION = '1.91.270.0', the release that shipped docs.caps. The comment states the convention: a new POLICY_KEY_INTRODUCED constant is written as a tentative future version (the next minor) in the _KEY_VERSION = '<version>' form, and the slot stamp moves it to the version actually released.
• .gstack/ship-policy.json: stamp_paths: ["lib/ship-policy.ts"] with stamp_patterns: ["_KEY_VERSION = '{version}'"], so gstack-restamp's stamp_paths stage moves a tentative key version at the slot. The stage reads the base branch's policy, so it is live from the next PR on; this PR's own slot stamps with the default --policy-from base and its constant is already the released value.
• test/gstack-ship-policy.test.ts: a released key's version must be a CHANGELOG heading whose entry names the key at a word boundary (keys that predate review_scope are exempt); a tentative value no stamp moved fails. Negative control: the old 1.91.258.0 value fails it, 1.91.270.0 passes. The test reads origin/main:CHANGELOG.md with a 64 MiB maxBuffer; at the default 1 MiB the 2 MB file ended ENOBUFS and the origin/main branch of the check was silently skipped.
• docs/ship-policy.md: the "gstack's own files" excerpt of .gstack/ship-policy.json now shows the two new keys.

Deferred findings

• Deferred review finding: lib/tree-receipt.ts:53 — stampOnlyHunks accepts a removed/added pair only as rewriteStamps(remo #3512 (blocking, outside the diff): lib/tree-receipt.ts:53 stampOnlyHunks, lib/ship-receipt.ts:178 stampOnlyText and scripts/train-gate.ts:143 stampFreeTree accept a stamp_paths move only when the old value equals the base VERSION. Under the next-minor convention the tentative value never equals the base version at the slot, so until Deferred review finding: lib/tree-receipt.ts:53 — stampOnlyHunks accepts a removed/added pair only as rewriteStamps(remo #3512 lands a PR that adds a key cannot clear the train's stamp-only receipt; the comment and the CHANGELOG entry say so. A second consequence, recorded on the issue: once lib/ship-policy.ts is a stamp path, train-backstop finds no covering record for main after the train that merges this PR and dispatches one redundant full gate (self-limiting once main moves past 1.91.270.0).

Review notes

Four passes under the frozen scope (pass 4 is the owner-granted re-read of the docs commit alone). Below the floor, left as notes:

• A --policy-from head restamp of this PR would move the just-corrected constant to the allocated version (the equal-base rule); the queue stamps with the base policy, so the path is unreachable through the train.
• The released-key regex accepts any <key>.<x> or <key>: token, so an unrelated entry mentioning such a token could satisfy it for a wrong heading; no present CHANGELOG section does.
• The test's base.status === 0 fallback still skips the origin/main branch silently on a checkout without that ref (shallow or remote-less clones), by design; a full clone now runs it.
• The stamp_patterns template _KEY_VERSION = '{version}' is a new template surface in gstack's own policy; its matcher is the existing restamp stage, unchanged here.
• Gate reuse: the remote gate at each head ran the whole free tier (11,413 tests); no paid own-case run was ordered for this change.

Documentation

Status: current — every audited doc agrees with the diff; the first attempt's blocker (the gstack's own files excerpt in docs/ship-policy.md showing stamp_paths: []) is repaired by bad9f53 and now matches .gstack/ship-policy.json byte for byte.

Scope. Base f27a760 → head bad9f53: .gstack/ship-policy.json, CHANGELOG.md, docs/ship-policy.md, lib/ship-policy.ts, test/gstack-ship-policy.test.ts; no staged, unstaged or untracked content. Audited docs/ship-policy.md (in full), docs/pregate.md, docs/troubleshooting.md, docs/review-policy.md, docs/releases.md, docs/CHANGELOG_STYLE.md and README.md against the diff. Banned terms: none (no list on main).

Documentation health: docs/ship-policy.md current (excerpt lines 88-89 name lib/ship-policy.ts under stamp_paths with the _KEY_VERSION = '{version}' template; schema rows, restamp stage 4, tree receipt and carry rule agree with the diff); docs/pregate.md, docs/troubleshooting.md, docs/review-policy.md, docs/releases.md, docs/CHANGELOG_STYLE.md and README.md current; CHANGELOG.md [Unreleased] over VERSION 1.91.270.0 is the accepted stamp-at-merge shape.

Documentation debt. The tentative next-minor convention for a new *_KEY_VERSION constant, and the interim rule that a key-adding PR cannot clear the train until #3512, are explained only in the lib/ship-policy.ts comment and the CHANGELOG entry, not in docs/ship-policy.md (an explanation paragraph under the gstack's own files section would fill it). The released-key CHANGELOG test is named in the CHANGELOG entry only. Diagram drift: none.

Test plan

• bun run typecheck clean; typecheck:test none new (9f1a6b3, 2bb3f58)
• bun test test/gstack-ship-policy.test.ts test/spawnsync-timeout-tripwire.test.ts test/changelog-merge-damage.test.ts 25 pass 0 fail at 2bb3f58; the 8-file focused set 319 pass at 9f1a6b3; test/compare-pr-version.test.ts test/ship-queue-train-logic.test.ts (the two tests naming docs/ship-policy.md) 49 pass at bad9f53
• dry-run proof in a scratch worktree with --policy-from head: a tentative 1.91.272.0 on a branch-added line moved to the allocated 1.91.271.0; with the default --policy-from base the stage reports skipped (no stamp_paths in policy)
• remote pregate (Ubicloud, whole free tier) at each head: 11,413 tests, 0 failed, $0.05 each (trees e45bc87f, 6bae99af, 11779f57, 9735ffc1)
• local pregate at bad9f53 requires-remote only; every requires-remote lane cleared by the pull_request run URLs; gstack-pregate verify ok
• every pull_request check at bad9f53 green

[trunk-io]

😎 This pull request was merged.