Skip to content

Explain how to merge any PR with gstack's land command (GST-2744) - #4377

Merged
capy-ai[bot] merged 3 commits into
mainfrom
docs/land-normal-merge
Nov 16, 2026
Merged

capy-ai[bot] merged 3 commits into
mainfrom
docs/land-normal-merge

Conversation

@garrytan

@garrytan garrytan commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

docs/ship-policy.md now explains how to merge any PR with gstack-ship-queue land, even in a repo with one maintainer: the two policy keys to set first, what land already checks, a pinned gh pr merge fallback, and four known traps.

Land refuses to run until a repo sets merge: direct and changelog_fragments, and nothing a maintainer reads first said so, so most repos kept merging by hand; CONTRIBUTING.md now points to the section.

Nothing to do: docs only, no behavior change.

Agent notes
  • Sources: org drive handoffs/gstack-generalize-audit-2026-11-15/land-adoption.md (build list item 1) and GSTA-550's report. Code read at main 8837fda: lib/ship-queue-land-direct.ts lines 160-161 (both refusals), 183-184 and 166 (open, pin, base), 227-233 (checks green with none pending, MERGEABLE and CLEAN), 49-67 (verify --pin checks only the receipt and gate dispositions); lib/ship-policy.ts DEFAULT_POLICY (merge: 'train', changelog_fragments: null); lib/ship-release.ts line 101 (fragments skip Step 12) and 142 (BUMP_ANSWER_REQUIRED); lib/release-stamp.ts line 56 (patch vs micro at release).

  • The minimal policy was checked with gstack-ship-policy validate: without min_gstack_version it fails (merge arrived in 1.95.0.0); with it, POLICY_VALID. bump: never next to changelog_fragments is refused, as the trap says.

  • Not documented on purpose: the squash body and a separate no-rewrite history rule (GST-2737, not shipped). Not claimed: that land can run the migration regate inside land.merged_checks (regate needs an evidence bundle and gh access, which merged checks don't have).

  • Unverified: gh exiting 0 when a GitHub merge queue later drops a PR is a team's report; I didn't test it.

  • Plan: exempt: audited-list (land-adoption audit 2026-11-15, build list item 1)

  • Review (one round plus one fix-check): the batched specialist found that the migration-collision trap named gstack-pregate regate without its required --against and --bundle arguments. Fixed in 5440076; the fix-check found nothing.

  • Second-pass review notes, all low and none blocking, left for a follow-up because the one fix round was used:

    1. ready --no-screen in the per-PR steps prints an "ignored" warning when the policy has no train block.
    2. "PATCH under patch, MICRO otherwise" leaves out that a changelog.d entry's bump: minor|major front matter raises the release size (lib/release-stamp.ts:56).
    3. The gh pr merge fallback doesn't say it skips land's merged_checks on a moved base and land's post-merge tree check.
    4. The new subsection sits between ### land --pin and that section's original opening paragraph, so #land-direct links now open on the new guide.
  • Docs audit: current, no edits.

Open in Capy

Agent notes
{
  "schema_version": 1,
  "pr": 4377,
  "head": "0c4a15a116ad46af27efd895bb7a4b88bff898a9",
  "version": "1.99.4.0",
  "base": "main",
  "gate": {
    "docs-links": {
      "pass": 1,
      "fail": 0,
      "skip": 0
    },
    "docs-readers": {
      "pass": 24,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "test",
      "run": 43670782901,
      "attempt": 1,
      "tree": "3010ea48827a17e9bd4eada415f9e61e674beac0"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "3010ea48827a17e9bd4eada415f9e61e674beac0",
  "product_patch_id": "5fbcb1fe7ba9bda1cce55b95a050f1b96c32496f",
  "gstack_version": "1.99.5.0",
  "review_depth": {
    "depth": "light",
    "class": "code",
    "runtime_lines": 121,
    "rules": "66e5174161eecc2c",
    "base": "0326b144af36676d599dcf63a9fad9a870d22ed6",
    "registry": "0326b144af36676d599dcf63a9fad9a870d22ed6",
    "gate_scan": {
      "tagged": 0,
      "head": "0c4a15a116ad46af27efd895bb7a4b88bff898a9"
    },
    "reasons": [
      "runtime=121"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "pass @3010ea48827a (8 checks, current for 0c4a15a116ad)",
  "docs": {
    "status": "current",
    "scope": "docs/, CONTRIBUTING.md, README.md (changed: docs/ship-policy.md, CONTRIBUTING.md, changelog.d/land-normal-merge.md)"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 0,
    "fixed": 1,
    "scope": "frozen",
    "fix_checks": 1,
    "rounds": 2,
    "dispatches": {
      "specialist": 1
    }
  },
  "gate_dispositions": []
}

docs/ship-policy.md opens its land section with the two policy keys a repo sets first, what land checks, a pinned gh pr merge fallback and four known traps; CONTRIBUTING.md points to it.

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

trunk-io Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 2 commits November 15, 2026 02:42
Review-Finding: p1/specialist-batched#1 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot merged commit eb0aa51 into main Nov 16, 2026
77 checks passed
@garrytan garrytan mentioned this pull request Nov 17, 2026
capy-ai Bot added a commit that referenced this pull request Nov 17, 2026
- /autoplan's approval page no longer hides a reviewer's product objection behind "keep your direction". (#4431)
- Every skill that loads the shared preamble, on every host, now says to ask a question once and to check a file before handing it over. (#4383)
- The Captain manuals now name the `Failed or skipped:` and `Also changed:` lines that READY and lane reports carry. (#4432)
- gstack's shell locks hold again on Ubuntu 26.04, where `mkdir` reports success when another process won the race (GST-2247). (#4262)
- `test/gstack-lock-race.test.ts` runs the old pattern and the helper against a PATH shim that behaves like uutils 0.8.0 `mkdir`, so it runs on any runner image: the old pattern lets two of four racers win, the helper admits exactly one in each of 60 races and never overlaps across take, hold and release loops, and parallel `gstack-config` writers keep every key. (#4262)
- Windows Setup E2E now runs when `bin/gstack-lock.sh` changes. (#4433)
- Claude Code's skill list now says when to use each gstack skill, so Opus loads /review and /plan-eng-review when a request fits. (#4387)
- A pull request's merge head can no longer keep its `/ship` receipt without a full review. (#4365)
- `/ship` now counts review rounds per pull request, and the head that merges always gets a full review. (#4360)
- /ship's documentation audit no longer accepts a passing result when an earlier line from the same audit said "blocked". (#4434)
- /ship's documentation audit no longer spends an attempt when the audit child writes text after its result. (#4285)
- The README lists the two new guides, and the install doc counts its hooks right. (#4403)
- docs/releases.md now says the stable release cut treats a failed commit status as red and a pending one as still going, as it has since #4257. (#4436)
- /ship's `finish --docs-requested` now accepts a docs fix when the audit named the file with a line number. (#4437)
- Document the `.gstack/approval-classes.json` schema, `gstack-approval-classes` CLI commands, and owner approval citation format in `docs/ship-policy.md#approval-classes`. (#4355)
- `/eval-plan` now runs four result checks instead of leaving them to judgment. (#4384)
- The /review coverage-audit eval no longer fails a run that really read the source file when zsh stops a command line at an `echo ====` separator. (#4364)
- Sixteen in-repo documentation links reach their section again. (#4394)
- gstack agents now open every status report with what failed, what they didn't verify and what else they changed. (#4273)
- Two new short guides. (#4380)
- A skill you wrote whose contract still lists `check_after_last_edit` keeps the rest of its contract. (#4439)
- The ship policy guide now explains how to merge any pull request with `gstack-ship-queue land`, even in a repository with one maintainer. (#4377)
- /ship's test step runs a large unit suite on Linux. (#4426)
- Every skill that loads the shared preamble, on every host, now says never to print a whole environment, git config or process table. (#4382)
- Pull requests from /ship now open with at most three plain lines, and every merge lands as one commit titled with the PR title. (#4438)
- `gstack-pr-wait`, `gstack-ci-gate` and the release cut no longer call a commit green while a check on it failed. (#4257)
- `gstack-runaway` now says what a thread's cold and empty wakes cost, not just how many there were (GST-2770). (#4385)
- The optional Stop hook no longer checks for a test run after the last edit, and /verify asks for it in plain words instead. (#4428)
- /ship's test step says when it ran out of time, and you can set its budget. (#4429)
- The remote test command no longer puts every file on one command line. (#4429)
- The stable release no longer waits on the nightly Windows tests (GST-2815). (#4400)
- Ubicloud fan-outs can no longer overshoot the vCPU limit, and owners no longer delete each other's VMs. (#4430)
- hono is pinned to 4.13.16, which fixes five advisories the weekly OSV scan found in 4.13.13 (gstack#4406). (#4408)
- `package.json` overrides (#4408)
- `test/dependency-security.test.ts`: the lockfile floor check now covers `hono >= 4.13.16`. (#4408)
- The nightly Windows test run finishes again. (#4409)
- A short write-up checklist in ETHOS.md. (#4381)

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