Skip to content

ship accept: a lanes-only head policy gates the final tree; owner-granted test-lane exception (GST-1595) - #4061

Merged
capy-ai[bot] merged 4 commits into
mainfrom
capy/gst-1595-accept-head-policy-lane-exception
Nov 6, 2026
Merged

capy-ai[bot] merged 4 commits into
mainfrom
capy/gst-1595-accept-head-policy-lane-exception

Conversation

@garrytan

@garrytan garrytan commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 4061,
  "head": "7bd50ffdf7d9b535f97934ec9e71ff5d1cacbbcd",
  "version": "1.96.0.0",
  "base": "main",
  "gate": {
    "tests": {
      "pass": 1604,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "tests",
      "run": 42198346836,
      "attempt": 1,
      "tree": "92aea4e6e34210ed6f008f787e8f4eac96b883db"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "92aea4e6e34210ed6f008f787e8f4eac96b883db",
  "product_patch_id": "1c64be236f87667d64cd4e44868d6c176e987991",
  "gstack_version": "1.96.0.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 367,
    "rules": "70895942bb8a8ee2",
    "base": "01572dec6d6627b7b96291e6276e9148b21a78b6",
    "registry": "01572dec6d6627b7b96291e6276e9148b21a78b6",
    "gate_scan": {
      "tagged": 0,
      "head": "7bd50ffdf7d9b535f97934ec9e71ff5d1cacbbcd"
    },
    "reasons": [
      "gate-class",
      "runtime=367"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @92aea4e6e342 (7 checks, current for 7bd50ffdf7d9)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/42198346836/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=92aea4e6e342 tests=35877 skipped=72 runs=42198346836/1 profiles=ci-reuse/free-tests heads=7bd50ffdf7d9 verified=2026-11-06T10:00:17.311Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "updated",
    "scope": "docs/, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, ARCHITECTURE.md, ship/, review/ (base 4b1a1152844a to eb64e2331e08)"
  },
  "review_loop": {
    "passes": 2,
    "blocking_found": 4,
    "deferred": 0,
    "noted": 9,
    "fixed": 6,
    "scope": "frozen",
    "fix_checks": 2,
    "rounds": 4,
    "ledgers_read": 5,
    "dispatches": {
      "specialist": 3,
      "red-team": 1
    }
  },
  "review_loop_exception": {
    "accepted_by": "GStack Minder (GSTA-36)",
    "date": "2026-11-06",
    "via": "approval a-eb67474cef62",
    "reason": "one scoped fix-check after round 2 for p2/red-team#1, the last exception for this PR",
    "fix_check": {
      "head": "eb64e2331e085cf132c5cabd0bfbc9274e650238",
      "findings": 1,
      "files": [
        "lib/pregate/head-policy.ts",
        "docs/pregate.md",
        "test/ship-accept-head-policy.test.ts"
      ]
    }
  }
}

What changed

accept honors a lanes-only head policy. gstack-ship-release accept (and finish when it reruns the whole pregate on the stamped tree) now pass --policy-from head when the branch's .gstack/pregate.json differs from the copy it forked from in nothing but added test lanes and .gstack/generated.json matches the base tip's copy. It prints POLICY: head (unreviewed) …. A removed or shrunk lane, any other changed key (warn, timeout_s, ship_lanes_from, …), or a generated.json that differs from main's keeps the base policy and prints POLICY: base … (the branch's copy <what differs> …). Helper: lanesOnlyHeadPolicy in lib/pregate/head-policy.ts.

accept and finish now gate the final tree under a branch policy that only adds test lanes, so a PR's own lane no longer fails with PREGATE_NO_LANE

accept and finish now gate the final tree under a branch policy that only adds test lanes, so a PR's own lane no longer fails with PREGATE_NO_LANE.

Before/after as text: accept and finish now gate the final tree under a branch policy that only adds test lanes, so a PR's own lane no longer fails with PREGATE_NO_LANE
--- Before · docs/pregate.md § Trust boundary at 4b1a115 · source text
+++ After · docs/pregate.md § Trust boundary on this branch · source text
@@ ⋯ 20 unchanged ⋯ @@
 `[]` declaration a branch adds counts only once it is on the base, and a lane it
 adds counts on the base policy only once it lands; `PREGATE_NO_LANE`'s fix line
 says so when the branch edits the file
+([troubleshooting](troubleshooting.md#pregate-no-lane-own-policy)).
+<a id="accept-head-policy"></a>/ship's reruns on the final tree (`gstack-ship-release accept`, and `finish`
+when it reruns the whole pregate on the stamped tree) choose the policy themselves
+(GST-1595). When the branch's `pregate.json` differs from the copy it forked from
+(the base tip's when the fork has none) in nothing but added test lanes, and
+`.gstack/generated.json` matches the base tip's copy (a head-policy run loads the
+regen registry from the branch, so a copy that main changed after the fork keeps
+the base policy), they pass `--policy-from head` and print
+`POLICY: head (unreviewed) .gstack/pregate.json: adds <n> test lane(s) over
+origin/<base> and changes nothing else, so the gate is only stricter`. So a PR
+that adds a runtime file and its own lane line passes `accept` without a
+lanes-only PR first (gstack-evals #240). Any other difference (a removed or
+shrunk lane, a `[]` declaration, `warn`, `timeout_s`, `ship_lanes_from`, any
+other key, a changed `generated.json`, a file that does not parse) keeps the
+base policy as before, with `POLICY: base origin/<base>:.gstack/pregate.json (the
+branch's copy <what differs>, so it does not count here; land it on <base>
+first)`. A branch that leaves the file alone prints no `POLICY:` line.
+An unresolvable base exits 3 with
-([troubleshooting](troubleshooting.md#pregate-no-lane-own-policy)). An unresolvable base exits 3 with
 `POLICY_SOURCE_UNAVAILABLE`. Globs are repo-relative (no `..`, no absolute
 paths, at most 64 per list); commands are one line under 512 bytes.
 

inventory_uncovered names the bun import pattern. When a carried lane's inventory file is in no run's tree.json and another inventory test file imports it, the refusal adds CARRY_DIAGNOSIS: bun registers <imported> under <importer>; its JUnit suite won't appear (importedTestLines in lib/ci-carry.ts). The remote gate's REUSE refusal uses the same helper.

Owner-granted test-lane exception. gstack-approvals lane-exception --head <pushed head> --files <exact files> --reason … --words … --by … records an approved row on the same trust path as ruled notes (#4050). It's refused inside the open /ship run, for a gstack actor, and through add, and a row gstack wrote is ignored. gstack-evidence record-ci binds it only at HEAD, only for the exact uncovered set, and only after a local per_file preflight of those files passes. The CI row and the receipt's ci_carried[].exception record it, accept prints TEST_LANE_EXCEPTION:, and gstack-ship-receipt write --body refuses a body without the Test-lane exception: … line.

Why

"accept refused my PR's own lane." GEVA-2 hit this on gstack-evals #240: the lane line passed preflight under --policy-from head, then accept failed with PREGATE_NO_LANE, and an imported test file's JUnit suite never showed up in CI's tree with no way to record an exception. Now a branch that only adds lanes passes accept, the carry refusal names the import that hid the suite, and the owner can grant a bound exception for exactly those files.

Tests

The test evidence is under Test Coverage and Test plan below.

Blast radius

The head-policy choice touches only the two pregate reruns in lib/ship-release.ts (finish at :536, accept at :590), and it can only make the gate stricter, because any difference beyond added lanes, or a generated.json that differs from main's, keeps the base policy (read at lib/pregate/head-policy.ts:85-104, failing-first test in test/ship-accept-head-policy.test.ts). The exception path changes nothing unless an owner row exists for the exact head and file set, and CI run 42198346836 passed the full free suite at this tree.

Approvals

Approved: yes (record r-b984cf13c625). The full approval record stays private: this repository is public or its visibility is unknown.

Summary

A PR that adds a runtime file and its own test lane was refused at accept because the final-tree pregate always used main's policy. accept and finish now use the branch's policy when it only adds lanes, carry refusals explain bun's imported-suite blind spot, and an owner can grant a narrow, head-bound test-lane exception that the receipt and PR body must disclose. The review rounds tightened the exception preflight, counted excepted files in tests_ran, bound grants to head and file set, and restored the base-tip generated.json comparison.

Test Coverage

Step 7 ran audit-only (no test-writing approval in this unattended run); the gaps it left are listed under Review notes.

  • test/ship-accept-head-policy.test.ts: the fix: repair workflow YAML parsing and lint CI #240 shape passes; a removed lane, a loosened check, an added lane plus timeout, an added lane plus a carry-map change, and main changing .gstack/generated.json after the fork all keep the base policy. The original cases fail on main 4b1a115; the generated.json case failed on b1f464a and passes at eb64e23.
  • test/ship-accept-lane-exception.test.ts: the import diagnosis; a granted exception binds and lands in the receipt and body; a grant at another head, for another file set, or with a failing preflight refuses; a lane-written grant refuses.
  • Focused suites at eb64e23 (8 files): all green, 106 cases with no failures.

Tests ran: tests 1604

Pre-Landing Review

Full panel, two rounds plus one owner-granted fix-check. Round 1 (p1, red-team at 46c37ef): four informational notes. Voices (v1: outside voice openai/gpt-6.1-sol and the native adversarial reader): five fixes in b1f464a (v1/outside-voice#1-3, v1/adversarial-native#2 and #4) and four notes. Round 2 (p2 at b1f464a): one blocking finding, p2/red-team#1 (the generated.json comparison moved to the fork point, so a branch could inherit a registry main had since changed); fixed in eb64e23. Fix-check at eb64e23 (fx2): no blocking finding, one wording note. An earlier fix-check attempt (fx1) was voided because a reader fetched outside its packet (FETCH_VIOLATION); its replies were quarantined and the stage reran clean as fx2.

REVIEW_LOOP: passes=2 blocking_found=4 deferred=0 noted=9 fixed=6 scope=frozen ledgers_read=5 fix_checks=2 dispatches=4

Review-loop exception: accepted by GStack Minder (GSTA-36) 2026-11-06 via approval a-eb67474cef62: one scoped fix-check after round 2 for p2/red-team#1, the last exception for this PR (fix-check at eb64e23, 1 finding)

Gate edits: none detected (2 listed, 0 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)

Outside review: openai/gpt-6.1-sol ran in the voices pass; three findings, all fixed.

Review notes

Below the blocking floor (advisory, informational, test-gap or wording items); recorded here and not fixed in this PR.

  • INFORMATIONAL lib/ship-release.ts:536 finish's full-pregate rerun on the stamped tree now picks its policy with lanesOnlyHeadPolicy and may pass --policy-from head, but no test drives finish on that path. test/ship-accept-head-policy.test.ts covers accept only, so if finish drops or mis-passes the flag, no test fails.
  • INFORMATIONAL lib/ci-carry.ts:102 Two refusal branches of the new exception path have no test: a matching grant on a lane with no per_file runner (inventory_uncovered with 'declares no per_file runner'), and a preflight that exits 0 but runs zero tests (exception_preflight_failed 'ran 0 tests' in bin/gstack-evidence). The only preflight test covers a non-zero exit.
  • INFORMATIONAL lib/pregate/index.ts:459 The remote gate's clearByRuns refusal now appends importedTestLines diagnoses to its inventory_uncovered / tests_uncovered message, but no test checks the pregate refusal. The only diagnosis test goes through record-ci and accept.
  • INFORMATIONAL lib/pregate/index.ts:459 The test-lane exception is honored only by gstack-evidence record-ci's findCarry. Pregate's own remote-gate carry (carryGate → clearByRuns) never consults it. In this repo, .gstack/pregate.json uses the exact same inventory command and profile (ci-reuse/free-tests, test-free-shards.ts --list) for both ship_lanes_from["bun run test"] and remote_gate_runs. So the file the owner excepted is still a required gate file. On a small machine (under SMALL_MACHINE_CORES = 8, which includes the 4-core Capy lanes), where the remote_gate obligation exists, clearByRuns refuses inventory_uncovered and the gate stays uncleared. The verdict is then requires-remote (1 uncleared), and accept stops at pregate … on the final tree after the lane already carried under the grant. The bound grant can't finish accept in gstack itself, which is the main flow docs/pregate.md#carry-imported-tests presents it as the remedy for. Neither new test fixture configures remote_gate_runs, so this path is untested.
  • INFORMATIONAL lib/pregate/head-policy.ts:90 2. git merge-base is never checked for failure (FIXABLE). In lanesOnlyHeadPolicy, if merge-base fails (a shallow clone or unrelated history), fork is empty and trusted falls back to the tip copy. If the base tip changed any other key since the fork, the branch's copy then reads as "also changes X" and keeps the base policy. This only causes false refusals and never loosens the gate.
  • INFORMATIONAL lib/test-lane-exception.ts:1 4. The grant trust model is advisory only (INVESTIGATE). The only guards are the openShipRun marker in this checkout, --by not naming gstack, and the refusal through add. A lane can still record a grant before it dispatches /ship, from another worktree, or by appending a row to the approvals jsonl. It can also put any owner name in --by, and nothing checks --words. This is the same m
  • INFORMATIONAL bin/gstack-ship-receipt:269 5. The new body enforcement disappears when ciCarried fails (INVESTIGATE). In bin/gstack-ship-receipt, ciCarried returns undefined on a timeout or bad JSON from gstack-evidence carried. The receipt then has no ci_carried, and laneExceptionBodyLines returns nothing, so the new "body must carry Test-lane exception:" rule passes silently. Swallowing this error was already there, b
  • INFORMATIONAL lib/test-lane-exception.ts:28 6. Grants can't be revoked, and NEXT quotes are escaped (FIXABLE). testLaneExceptions skips rows that are not approved, so a later declined row never cancels an earlier grant, and lane-exception can't write a non-approved row at all. The only way out is a new push, since grants are bound to a head. Separately, accept's NEXT: line wraps the body line in JSON.stringify, so a reason conta
  • INFORMATIONAL lib/pregate/head-policy.ts:103 A lanes-only branch that never touched .gstack/generated.json, where main changed that file after the fork, now keeps the base policy. That is the intended fail-closed result. But accept and finish print the shared keep() line: "the branch's copy comes with a changed .gstack/generated.json ... land it on main first". That blames the branch and gives the wrong fix. The branch has nothing to land, and the real remedy is to bring main's generated.json onto the branch (the test case at test/ship-accept-head-policy.test.ts:64 reproduces this path and locks in the wording).

Exploratory QA

Smoke probes of gstack-approvals lane-exception in a fixture repo, all six green: a grant records at a real head; whitespace in --files, --by gstack, add with a test_lane_exception scope, and an unknown head all refuse; the grant reads back with ./ stripped and files sorted. Not probed here: record-ci binding, accept and the head-policy rerun (covered by the focused suites), and the open-/ship-run refusal (test/ship-accept-lane-exception.test.ts:133).

Design Review

No frontend files changed — design review skipped.

Eval Results

No prompt-related files changed — evals skipped.

Review bot comments

No review bot comments.

Issues

Refs p2/red-team#1
Refs v1/adversarial-native#2
Refs v1/adversarial-native#4
Refs v1/outside-voice#1
Refs v1/outside-voice#2
Refs v1/outside-voice#3

TODOS

No TODO items completed in this PR. The TODOS.md P2 item "finish fallback drops head-policy lanes" is partly addressed (finish now reruns under the head policy for lanes-only branches) and was left open for its owner to confirm.

Documentation

Status: updated. Four factual edits in docs/troubleshooting.md bring its result-code entries in line with GST-1595; no blockers.

Scope. Base 4b1a1152844a to head eb64e2331e08 on capy/gst-1595-accept-head-policy-lane-exception: 3 commits, 19 committed files, and no staged, unstaged or new files. Changed public surface: gstack-approvals lane-exception; the POLICY: head|base line that gstack-ship-release accept and finish print; CARRY_DIAGNOSIS:; the exception_preflight_failed refusal; TEST_LANE_EXCEPTION: and the Test-lane exception: … body line; and the optional ci_carried[].exception field in the receipt. I checked the branch's own doc changes (docs/pregate.md#accept-head-policy, #carry-imported-tests, docs/ship-policy.md#test-lane-exceptions) against the code, and they are accurate. Banned-terms check: none (no list on main).

Documentation health:
  docs/troubleshooting.md        Updated (APPROVAL_RECORD_INVALID: added rule and lane-exception refusals and that add refuses their scopes;
                                 RECEIPT_INVALID: added write --body refusing a body that lacks a Ruled note, Mechanical retake or Test-lane exception line;
                                 PREGATE_NO_LANE own-policy: added that accept and finish choose --policy-from head for lanes-only branches;
                                 RECEIPT_PROSE_MISMATCH: listed every exception line kept out of the prose check)
  docs/pregate.md                Current (branch-added sections match lib/pregate/head-policy.ts, lib/ci-carry.ts and bin/gstack-evidence)
  docs/ship-policy.md            Current (test-lane exceptions section matches bin/gstack-approvals and lib/test-lane-exception.ts)
  docs/standalone-binaries.md    Current
  ship/sections/pr-body.md.tmpl  Current, with a gap (see debt)
  ship/sections/tests.md.tmpl    Current
  ship/SKILL.md.tmpl             Current
  ship/DRIVER.md.tmpl            Current
  CHANGELOG.md                   Skipped (ship-owned: not audited for voice; the changelog.d fragment was left unchanged)
  TODOS.md                       Skipped (ship-owned: Step 7 not run)

Documentation Debt

  • ⚠️ Test-lane exception: … PR-body line: covered by reference docs (ship-policy.md, pregate.md, troubleshooting.md), but the how-to is missing. ship/sections/pr-body.md.tmpl lists the Ruled note: and Mechanical retake: lines the receipt write requires and leaves this one out. Today only accept's NEXT: line tells the agent to add it.
  • ⚠️ CARRY_DIAGNOSIS: and exception_preflight_failed: reference only (pregate.md). Neither has a troubleshooting.md entry (how-to quadrant).
  • ⚠️ gstack-approvals lane-exception: reference and how-to exist, with no tutorial. This is low priority for an owner-only command.
  • Minor: the ci_carried: [{ lane, run, attempt, tree }] shape at docs/pregate.md (Finish, push and accept) leaves out the optional exception field. The next paragraph documents it.

Diagram drift: none. ARCHITECTURE.md has no diagrams that name the pregate, CI carry or ship-release entities.

docs/troubleshooting.md is an authored doc with no generator entry, so nothing needs regenerating. If you want the pr-body gap filled, /document-generate can do it, or you can make a parent-owned template edit.

Test plan

  • bun run test: carried from free-tests.yml run 42198346836 at tree 92aea4e6e342 (1604 files, green; CI_CARRY accepted)
  • macos-named-regressions: green in run 42198346836, cleared in pregate
  • Focused suites (8 files) at eb64e23: all green, 106 cases with no failures

🤖 Generated with Claude Code

Open in Capy

…hidden JUnit suites; owner-granted test-lane exception (GST-1595)

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

trunk-io Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 3 commits November 6, 2026 09:12
Each excepted file is preflighted on its own and must run a counted test; the preflighted files count toward the lane's tests_ran; grants are kept per head and file set; lanesOnlyHeadPolicy compares .gstack/generated.json with the fork copy.

Review-Finding: v1/outside-voice#1 reader=outside-voice
Review-Finding: v1/outside-voice#2 reader=outside-voice
Review-Finding: v1/outside-voice#3 reader=outside-voice
Review-Finding: v1/adversarial-native#2 reader=adversarial-native
Review-Finding: v1/adversarial-native#4 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
A --policy-from head run loads the regen registry from the branch (lib/pregate/context.ts), so a branch whose .gstack/generated.json differs from main's tip keeps the base policy; comparing with the fork copy would gate under a stale registry.

Review-Finding: p2/red-team#1 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…e exceptions (GST-1595)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot merged commit 05114c8 into main Nov 6, 2026
68 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