Skip to content

v1.91.257.0 feat(pregate): clear --receipt accepts a remote_gate receipt from a stamp-only predecessor tree (gbrain gate-ahead) - #3486

Merged
capy-ai[bot] merged 6 commits into
mainfrom
gsta-117/pregate-remote-stamp-only
Oct 26, 2026
Merged

capy-ai[bot] merged 6 commits into
mainfrom
gsta-117/pregate-remote-stamp-only

Conversation

@garrytan

@garrytan garrytan commented Oct 26, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 3486,
  "head": "b2b2be2e41676e015be274709ac96ea7304d1034",
  "version": "1.91.254.0",
  "base": "main",
  "gate": {
    "tests": {
      "pass": 11839,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "pregate": "requires-remote cleared @9fe256f13cc8 (1 checks, current for b2b2be2e4167)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/40395518499",
    "windows-free-tests.yml/windows-free-shard: https://github.com/garrytan/gstack/actions/runs/40395524180",
    "pregate.json/remote_gate: remote-gate tree=9fe256f13cc8 tests=11839"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  }
}

What changed

gstack-pregate clear --remote pregate.json/remote_gate --receipt <file> now accepts a remote-gate receipt whose tree is a stamp-only predecessor of the tree pregate.json recorded, and records the substitution. Before, the receipt's PREGATE_REMOTE: tree=… had to equal pregate.json's tree exactly, so a full gate that ran ahead of /ship's restamp (the "gate ahead of your turn" case gbrain's shipping rules allow) could never clear the small-machine obligation, and every gbrain PR paid a second full gate after /ship (gbrain #7621, #7674, #7681: 17–37 min, 64–128 vCPU each at a 512 quota).

A remote-gate receipt from the stamp-only predecessor tree now clears pregate.json/remote_gate and records the substitution; before, it was refused and gbrain paid a second full gate per PR

A remote-gate receipt from the stamp-only predecessor tree now clears pregate.json/remote_gate and records the substitution; before, the same receipt on the same head was refused. Captured from the test fixture: before is the installed gstack v1.91.253.0 (main), after is this branch.

Before/after as text: A remote-gate receipt from the stamp-only predecessor tree now clears pregate.json/remote_gate and records the substitution; before, it was refused and gbrain paid a second full gate per PR
--- Before · before.txt · captured output
+++ After · after.txt · captured output
+$ gstack-pregate clear --remote pregate.json/remote_gate --receipt gate.log   # this branch
+PREGATE_RECEIPT_SUBSTITUTED: gated tree 8fed2a7dff8b accepted for tree b69b4832bfac under origin/main@da6c9aa2fb9c:.gstack/ship-policy.json; stamp-only: CHANGELOG.md (changelog-heading), README.md (stamp_files), VERSION (version-file), package.json (manifest-version), plugin.json (stamp_files)
+PREGATE_CLEARED: pregate.json/remote_gate receipt=remote-gate tree=8fed2a7dff8b tests=3 accepted-for=b69b4832bfac stamp-only=5 receipt=gate.log sha256=5839a360578a verdict=requires-remote cleared
+exit 0
+$ gstack-pregate verify
+PREGATE_VERIFY: ok pregate requires-remote cleared is current for tree b69b4832bfac; pregate.json/remote_gate: gated tree 8fed2a7dff8b accepted for tree b69b4832bfac under origin/main@da6c9aa2fb9c:.gstack/ship-policy.json; stamp-only: CHANGELOG.md (changelog-heading), README.md (stamp_files), VERSION (version-file), package.json (manifest-version), plugin.json (stamp_files)
+exit 0
-$ gstack-pregate clear --remote pregate.json/remote_gate --receipt gate.log   # gstack v1.91.253.0 (main)
-gstack-pregate clear: receipt refused — the remote gate tested tree 8fed2a7dff8b, not b69b4832bfac; pregate.json/remote_gate stays uncleared; fix: rerun the remote gate on this tree and pass its output with `gstack-pregate clear --remote pregate.json/remote_gate --receipt <file>`, or run `gstack-pregate --stage tests --remote --spend-cap <usd> --allow-repo-commands` (PREGATE_RECEIPT_INVALID; https://github.com/garrytan/gstack/blob/main/docs/troubleshooting.md#pregate-receipt-invalid)
-exit 1
 

The rule is the tree receipt's rule, not a new one

lib/pregate/remote-receipt.ts (substituteStampOnlyTree) diffs the two trees and classifies every differing file with classifyFile from lib/tree-receipt.ts, under .gstack/ship-policy.json on origin/<base> (stamp_files, stamp_patterns with their {version} templates, and the built-in version-file, version-manifest, manifest-version, lockfile-root-version and changelog-heading forms, all through stampOnlyHunks / rewriteStamps). There is no second stamp-path list and no looser rule: the test asserts the recorded files: [{ path, rule }] equals gstack-tree-receipt --gated G --current H's file verdicts on the same pair, and that a stamp path with a non-stamp hunk is changed in both. The tree receipt's gate rule holds too: a base policy whose stamp_sensitive_gates names the test lane (tests or remote_gate; gstack's own policy lists tests) refuses the substitution, because that receipt never marks the test lane reusable across a stamp. So gstack itself never substitutes; gbrain, whose policy does not list its test lane, does.

The diff is read with a fixed presentation (--no-textconv --no-renames --ignore-submodules=none, a/ b/ prefixes) and reconciled against git diff-tree's path inventory, so a diff driver or diff.* setting can neither hide nor rename a path. Both trees must be 40- or 64-hex object ids and objects in the repository (the gated commit fetched; the head tree is what bin/gstack-wtree wrote). An unfetched gated tree, a symbolic tree, an unreadable, unfetched or invalid base policy, a pregate.json recorded with --base against another branch than origin/HEAD's (the fix names git remote set-head when origin/HEAD is unset), or two trees at the same version for a stamp_files hunk are refused, never trusted. The receipt's own tests/failed checks run before any git work. clearDecision without a repository root (library callers) keeps the exact tree-mismatch refusal as before.

What is recorded

  • The receipt string gains accepted-for=<head> stamp-only=<n> after tests= (the ship receipt's requires_remote row carries it).
  • pregate.json's obligation gains substitution: { gated_tree, accepted_for, policy, files: [{ path, rule }] } (schema and PregateReceiptSubstitution type in lib/headless-artifacts.ts).
  • clear prints PREGATE_RECEIPT_SUBSTITUTED: …; verify repeats the substitution on its ok line; a substitution whose accepted_for is not pregate.json's tree, or whose gated_tree is not the receipt string's tree=, is PREGATE_REMOTE_UNCLEARED ("clear again").

Read-only files touched

lib/tree-receipt.ts: only export added to classifyFile (no other change), so pregate imports the rule instead of restating it. lib/restamp.ts, scripts/pregate-remote-gate.sh, scripts/ubicloud/pregate-remote.sh and what the remote gates print are untouched.

Docs

docs/pregate.md#remote-gate-stamp-only: what is accepted and refused, that a consuming repo declares its stamp paths once in .gstack/ship-policy.json on its base branch (the file the tree receipt and restamp already read; nothing new in .gstack/pregate.json), and the four-command sequence that reuses a gate-ahead run. The PREGATE_RECEIPT_INVALID and PREGATE_REMOTE_UNCLEARED anchors in docs/troubleshooting.md explain every refusal line and the misapplied-substitution case.

Why

GBrain Minder's ask, routed by GStack Minder as GSTA-117: gbrain's remote gate is bound to the exact tree, its rules let a head reuse a full gate whose tree differs only in release stamps, but /ship's Step 12 restamp always changes those files, so the gate-ahead path never satisfied remote_gate and every gbrain PR ran the whole gate twice. The fix reuses gstack's existing stamp rule so the pregate verdict and the tree-receipt verdict can never disagree. After this lands, gbrain fetches the gated commit, runs gstack-pregate --allow-repo-commands on the stamped head, clears with the gate-ahead output, and verify passes with the substitution on record.

Approvals

Date Asked Exact words Outcome Covers Still pending
2026-10-26 GSTA-117 lane: let gstack-pregate clear --receipt accept a remote_gate receipt from a stamp-only predecessor tree, using lib/tree-receipt.ts own rule (gbrain gate-ahead ask) “lane brief from GStack Minder (GSTA-36) with the done-means list; declaration in the file tree-receipt already reads; --no-screen if no skill prompt changed; paid eval cap $10; open the PR even if #3480 has not merged and tell me” (GStack Minder (GSTA-36), routing GBrain Minder and Garry) approved this PR (#3486): lib/pregate, bin/gstack-pregate, docs/pregate.md remote-gate section, troubleshooting anchors, tests none

Source: gstack-approvals record for gsta-117/pregate-remote-stamp-only (display only; not an approval citation).

Coordination

#3480 (GSTA-112, pregate ergonomics) rewrites parts of lib/pregate and was still OPEN when this PR was opened; this branch is from main. The overlap is lib/pregate/index.ts (verifyPregate's tail and clearDecision), lib/pregate/checks/lanes.ts (one added export), lib/headless-artifacts.ts (adjacent schema fields) and bin/gstack-pregate (adjacent lines in cmdClear/HELP); none of #3480's hunks touch the lines this PR changes, so the train merge should be clean, and if not, #3480's structure wins. #3480 merged as v1.91.254.0 (main 568cd5a) and the train's scratch merge hit a real conflict in lib/headless-artifacts.ts, so under GStack Minder's rule 19 grant main is merged into this branch (b2b2be2): the PregateFile schema keeps #3480's checks cause/environment and scratch with this PR's requires_remote[].substitution appended, and the CHANGELOG is additive (our entry stays under [Unreleased], VERSION at main's 1.91.254.0).

Summary

  • pregate: stamp-only substitution for the remote_gate receipt — lib/pregate/remote-receipt.ts (new), lib/pregate/index.ts (clearDecision takes the repo root; verifyPregate checks accepted_for and gated_tree), lib/pregate/checks/lanes.ts (exports treeMismatch), bin/gstack-pregate (prints PREGATE_RECEIPT_SUBSTITUTED, HELP), lib/headless-artifacts.ts (schema).
  • Hardening from review — fixed diff presentation and diff-tree reconciliation, stamp-sensitive-lane and base-branch refusals, hex object-id guard, unreadable-policy refusal, receipt checks before git work.
  • Docs and CHANGELOG — docs/pregate.md#remote-gate-stamp-only, two troubleshooting anchors, ## [Unreleased] entry (VERSION, package.json and the digest stay at main's; the train stamps at the slot).

Test Coverage

All new code paths have test coverage. test/pregate-remote-stamp-only.test.ts (10 tests, 94 assertions): accept with the recorded substitution equal to the tree receipt's verdicts and verify ok; the unchanged same-tree path (no substitution); a same-tree re-clear dropping the substitution; refusals for a path outside the rule, a stamp path with a real change, an unfetched gated tree, an unreadable receipt file, zero tests, a failure, a symbolic tree, a head tree not in the object store, a mode-only difference, a stamp file at the wrong version, a pregate.json recorded against another base (with and without origin/HEAD), an invalid base policy and a stamp-sensitive test lane; verify on a misapplied accepted_for and on a swapped gated_tree.

Tests ran: tests 11813 pass, 0 fail (full free tier on one Ubicloud VM at the final tree 9fe256f13cc8, main 568cd5a merged in, PREGATE_REMOTE: tree=9fe256f13cc8… tests=11839 failed=0 spent=0.05; the pre-merge trees e9c1872778de and 722d3f984f44 passed the same way, 11813/0 each).
Tests ran: focused 630 pass, 0 fail across 32 files on the merged tree (pregate-, tree-receipt-, headless-artifacts, module-size-ratchet, changelog-*, troubleshooting-anchors, test-free-shards, ubicloud-pregate-remote); 290/0 across 26 files before the merge.
Tests ran: typecheck clean; typecheck:test ratchet 819 known, none new.
Local bun run test:quick on the 4-core machine failed 15 tests in 13 browse/CSO-witness/gbrain-mcp/Chromium files for environment reasons (Playwright's chromium_headless_shell not installed; generated .agents/skills/*/SKILL.md absent). None reference pregate, tree-receipt or headless-artifacts, and the same files pass on the Ubicloud run above where setup is complete.

Pre-Landing Review

Three passes (crew rule 23), all read-only, records persisted with gstack-review-log --finish; each record's review_binding is changed because the pass's findings were fixed in the tree while the next pass ran, so gstack-review-read reports them STALE/UNVERIFIED rather than verified. After the adversarial pass: the win32 describe.skipIf on the test file (test-only), then the merge of main 568cd5a (v1.91.254.0, #3480) under GStack Minder's rule 19 grant, reviewed by one more delta pass (token 18f58ffe, no findings: the schema resolution keeps #3480's cause/environment/scratch and this PR's substitution; clearDecision never reaches #3480's environment classifier; pregate.json and receipt paths are unmoved by the per-run scratch directory):

  • Pass 1 (full diff at 727eb6c, 5 specialists + red team): 1 CRITICAL (lib/pregate/remote-receipt.ts:91:gate-reuse-bypass — a policy whose stamp_sensitive_gates names the test lane must refuse) fixed; 14 informational fixed; skipped as advisory: remote-receipt.ts:84:performance (no early exit on the first changed file), index.ts:205:integration-boundary, two simplification notes.
  • Pass 2 (delta 3732bbb..727eb6c): 2 informational, both fixed (CHANGELOG Tests bullet; --base main fix text when origin/HEAD is unset).
  • Adversarial, native + outside voice (full tree at 727eb6c): 13 findings, 0 critical. Fixed: diff presentation / textconv / submodule concealment and diff-tree reconciliation; existing-but-unreadable base policy loading as defaults; receipt checks ordered before git work; verify not binding gated_tree to the receipt. Deferred as advisory or pre-existing (listed below).
  • No finding met the blocking floor (fails a test, breaks production, loses data or secrets) after pass 1.

Gate edits: 1 listed, 0 eligible, 0 read, 0 findings — 0 kept, 0 restored, 0 open (GATE_SUMMARY … unmatched=9 candidate=8663c3d25fdc+722d3f984f44; the only listed path is the new test file).
Outside review: GPT-6.1 adversarial pass ran (2 findings, both fixed); Codex CLI not installed on this machine, so no Codex verdict (missing coverage, not passed).

Deferred (advisory / pre-existing, not fixed here):

  • The substitution is on for any repo whose base policy does not list its test lane in stamp_sensitive_gates (that is the tree receipt's rule and the lane brief: no stricter or looser rule); a repo with no policy at all substitutes under the built-in version-file/manifest/lockfile/changelog forms only.
  • The receipt is a trust input (hand-writable), as the same-tree receipt already was; no ancestry check between the gated tree and the head.
  • Built-in rules compare content and do not check the direction of the version move or cross-file consistency (lib/tree-receipt.ts, read-only).
  • lib/evidence-bundle.ts lockfile normalizer strips the first "version" line only (pre-existing, read-only).
  • CHANGELOG normalization replaces the heading line and sorts sections (lib/changelog-check.ts, pre-existing).
  • A pregate.json recorded with --base release/x never substitutes while origin/HEAD is main (fails closed; clear has no --base).
  • The recorded file list and verify's ok line are uncapped.
  • Pre-existing doc debt: docs/pregate.md synopsis omits clear --receipt; docs/pregate.md ~272 and ship/sections/pr-body.md.tmpl say PREGATE_REMOTE_UNCLEARED clears with a run URL, which the remote_gate lane refuses.

Exploratory QA

Not run: no browser, API or worker surface changed. The CLI path is exercised end to end by the test file (runBin) and the before/after capture above.

Design Review

No frontend files changed — design review skipped.

Eval Results

No prompt-related files changed — evals skipped (no skill template or SKILL.md in the diff).

Scope Drift

Scope Check: CLEAN — every changed file is in the lane's owned set (lib/pregate/**, bin/gstack-pregate, docs/pregate.md remote-gate section, additive troubleshooting anchors, test/pregate-*.test.ts, CHANGELOG), plus the one export in lib/tree-receipt.ts named above.

Issues

ISSUE_LINKS: none

Verification Results

Obligations: remote gate on the final tree PASS (11813/0); focused suites PASS; typecheck PASS; docs audit twice, corrections applied (see Documentation); macOS and Windows CI lanes dispatched on b2b2be2 (free-tests 40395518499 green, windows-free-tests 40395524180 green; on the pre-merge head 60ee688: 40383966238 and 40383971192, both green), both cleared into pregate.json; gstack-pregate verify: ok for tree 9fe256f13cc8. The first Windows dispatch on 6c536a7 (40382437284) failed only in the new test file, which expects the Linux-host lanes verdict like test/pregate-remote.test.ts; the suite now skips itself on win32 (scripts/lib/windows-curation.ts is held by #3478, #3480 and #3484, so the curation entry is left for whoever owns that file).

TODOS

No TODO items completed in this PR.

Documentation

Status: audited twice, read-only (/document-release spawned, attempt budget of two used); both audits returned blocked only because read-only mode barred the auditor from writing its corrections, and every correction is applied in this head by the parent. Named risk: the final wording edits (docs/pregate.md "tests and failed checks" sentence, the gated_tree clause, CHANGELOG Added/Tests bullets) were verified against the code by the parent, not by a third audit.

Scope: base 8663c3d → head on gsta-117/pregate-remote-stamp-only; docs/pregate.md (changed regions and neighbours, then in full), docs/troubleshooting.md (PREGATE_RECEIPT_INVALID, PREGATE_STALE, PREGATE_REMOTE_UNCLEARED), docs/ship-policy.md, CHANGELOG.md [Unreleased], bin/gstack-pregate --help, against lib/pregate/remote-receipt.ts, lib/pregate/index.ts, lib/pregate/checks/lanes.ts, lib/tree-receipt.ts classifyFile, lib/ship-policy.ts, lib/result-codes.ts, lib/headless-artifacts.ts. gstack-banned-terms: none.

Corrections applied: the clean-checkout paragraph now precedes the command-sequence lead-in; version-manifest added to the rule list; the receipt's exit status is not re-checked on clear --receipt (only --remote checks exit 0), and the docs and CHANGELOG now say so; #pregate-receipt-invalid gained the stamp-sensitive-lane, other-base and unreadable/invalid-policy refusals; #pregate-remote-uncleared and the CHANGELOG name the gated_tree check.

Debt (not filled here): README, CLAUDE.md and docs/skills.md do not link docs/pregate.md (pre-existing); the pre-existing synopsis and run-URL wording listed under Deferred above. No diagram drift.

Test plan

  • gstack-pregate --stage tests --remote --spend-cap 2 --timeout 2700 --allow-repo-commands (Ubicloud standard-16, 300 s, $0.05): PREGATE_REMOTE: tree=9fe256f13cc8717580903edb0cea20acc9f79548 tests=11839 failed=0 (and 11813/0 on each of the two pre-merge trees, $0.05 each)
  • bun test --timeout 120000 test/pregate-*.test.ts test/tree-receipt-*.test.ts test/headless-artifacts*.test.ts test/module-size-ratchet.test.ts test/changelog-*.test.ts test/ubicloud-pregate-remote.test.ts: 290 pass, 0 fail
  • bun test --timeout 120000 test/troubleshooting-anchors.test.ts test/pregate-remote-stamp-only.test.ts test/changelog-merge-damage.test.ts: 254 pass, 0 fail
  • bun run typecheck clean; bun run typecheck:test 819 known diagnostics, none new
  • free-tests.yml (40395518499) and windows-free-tests.yml (40395524180) on b2b2be2, both green
  • bun test --timeout 120000 test/pregate-*.test.ts test/tree-receipt-*.test.ts test/headless-artifacts*.test.ts test/module-size-ratchet.test.ts test/changelog-*.test.ts test/troubleshooting-anchors.test.ts test/test-free-shards.test.ts test/ubicloud-pregate-remote.test.ts on the merged tree: 630 pass, 0 fail
  • bun test --timeout 120000 test/pregate-remote-stamp-only.test.ts test/test-free-shards.test.ts: 87 pass, 0 fail

🤖 Generated with Claude Code

…tamp-only predecessor tree (gbrain gate-ahead)

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

trunk-io Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 4 commits October 26, 2026 18:35
…and base-branch refusals, one substitution type, docs)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ff-tree reconciliation), refuse an unreadable base policy, check the receipt before git work, bind verify to the receipt tree; docs audit corrections

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ict; skip itself on win32 like test/pregate-remote.test.ts

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

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ipt from a stamp-only predecessor tree (gbrain gate-ahead) (#3486)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@github-actions github-actions Bot changed the title feat(pregate): clear --receipt accepts a remote_gate receipt from a stamp-only predecessor tree (gbrain gate-ahead) v1.91.257.0 feat(pregate): clear --receipt accepts a remote_gate receipt from a stamp-only predecessor tree (gbrain gate-ahead) Oct 26, 2026
@capy-ai
capy-ai Bot merged commit 7f53ddb into main Oct 26, 2026
70 of 72 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant