Skip to content

Make the behind= trailer and rebase rules agree across gstack docs (GST-2136) - #4224

Merged
capy-ai[bot] merged 3 commits into
mainfrom
fix-behind-trailer-and-rebase-docs
Nov 9, 2026
Merged

capy-ai[bot] merged 3 commits into
mainfrom
fix-behind-trailer-and-rebase-docs

Conversation

@garrytan

@garrytan garrytan commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Agents now get one answer when gstack's install check says their copy is behind (run the fix it prints before the next workflow), and the unattended docs now say a branch whose base moved is merged, never rebased. That keeps crews on current gstack and keeps reviewed branches intact.

What changed

  • Behind trailer (C20). Every place the install-trailer rule is written now says the same thing. behind=1 or more means run the trailer's fix before the next workflow. Two things still hold the checkout where it is: a pin with a recorded reason (a stale=<h>h (pinned: <why>) note, or a fix: starting unset GSTACK_CAPY_, which is skipped while the reason is recorded), and an install that was refused (upgrade skipped: … (<CODE>)). Files: capy/skill/gstack/SKILL.md, capy/skill/gstack/lane-card.md, docs/capy-install.md, docs/troubleshooting.md, a comment in bin/gstack-capy-install, a test comment in test/capy-skill-wrapper.test.ts, and the UPGRADE_SKIPPED fix string in lib/result-codes-capy.ts.
  • Merge, never rebase (C5). docs/unattended.md now says a moved base is merged in, never rebased, and no longer names "the slot call" as a reason to rebase. The rule it points to is docs/ship-policy.md, section "Carrying a receipt across a base merge or a test-only fix" ("Merge main into a reviewed branch; never rebase it"), which crew/docs/captain.md L442 repeats.
  • A changelog fragment, changelog.d/fix-behind-trailer-and-rebase-docs.md. VERSION, package.json and CHANGELOG.md are untouched; the merge stamps them.

Why

The Capy skill said both "run the fix" and "behind= alone is informational" about the same trailer, so most lanes took the second reading and kept working on an old gstack. FOUN-35's audit found 113 of 150 follow-up trailers at the same or an older revision than the first one. The rebase wording was a second contradiction: docs/unattended.md let a slot call rebase a reviewed branch, while ship-policy.md says to merge.

Blast radius

Only prose changed, plus one comment, one test comment and one fix string. No runtime logic moved, so every install, upgrade and pin behaves as before. The pin case was checked against bin/gstack-capy-session L139-176 and L229-241 (file:line read): a reasoned pin still holds, because the docs now tell agents to skip the unset GSTACK_CAPY_ fix while a reason is recorded. The Drive copy of the Capy skill does not update itself, so the owner recopies it after merge.

Pre-Landing Review

No blocking issues remain. The one blocker (outside voice, openai/gpt-6.1-sol: following the new rule would unset a deliberate pin under 24 hours old) was fixed in 8e64a8a. A scoped fix-check the Captain granted past the round cap reviewed that fix and found nothing blocking.

Gate edits: none detected (1 listed, 1 read).

Outside review: openai/gpt-6.1-sol at 0e737b3 found 1 blocker, now fixed and fix-checked at 8e64a8a.

Review notes

Below the blocking floor; recorded here and not fixed in this PR.

  • Low bin/gstack-capy-session:244 The stale message still says "run the fix before the first workflow", while the docs now say "next workflow". Tests at test/capy-skill-wrapper.test.ts:797 and :1226 pin the string.
  • Low capy/skill/gstack/SKILL.md step 2 The "behind=1 or more" rule does not say it applies only to gstack: ok <revision> for=<skill> trailers, not for=none ones.
  • Low capy/skill/gstack/SKILL.md step 2 The rule does not say whether the fix runs once per session or once per workflow.
  • Low docs/unattended.md The closing sentence names only a plan-named rebase and drops the /modernize disposition the bullet above it allows.
  • INFORMATIONAL capy/skill/gstack/SKILL.md:13 The skip clause for a fix: starting unset GSTACK_CAPY_ does not restate its condition (a recorded reason) as a check the agent runs; docs/capy-install.md:143 does.
  • INFORMATIONAL capy/skill/gstack/SKILL.md:13 Step 2's reason list names GSTACK_PIN_REASON and gstack.pinReason, not --revision or gstack.contributor, which the wrapper also counts.
  • INFORMATIONAL capy/skill/gstack/SKILL.md:13 The skip clause is not limited to ok trailers. A fail revision trailer with AUTO_UPGRADE=0 and a recorded reason would skip its only fix; this fails closed.
  • INFORMATIONAL capy/skill/gstack/SKILL.md:13 Step 2 now says a thread older than a day reruns the check before its next workflow, dropping "once its last check is over 24h old".

Test Coverage

No changed executable paths, so there are no coverage gaps.

Eval Results

No paid evals ran. eval:select picked dependency-derived behaviors from a bin comment and a lib fix string, and that selection was over the $10 per-PR cap.

TODOS

No TODO items completed in this PR.

Documentation

Status: current. No documentation edits were needed; the branch's own doc changes are consistent and complete.

Scope: the 9 committed files from base 324135d to head 8e64a8a (GST-2136): capy/skill/gstack/SKILL.md, capy/skill/gstack/lane-card.md, docs/capy-install.md, docs/troubleshooting.md, docs/unattended.md, changelog.d/fix-behind-trailer-and-rebase-docs.md, plus the doc-bearing source bin/gstack-capy-install, lib/result-codes-capy.ts and test/capy-skill-wrapper.test.ts. I grepped the whole repo's authored .md and .tmpl files for behind=, stale= and rebase wording, and checked crew/docs/recommended-harness.md and docs/ship-policy.md as cross-references.

Documentation health:

  • capy/skill/gstack/SKILL.md: current (step 2 now says behind=1 or more calls for the fix)
  • capy/skill/gstack/lane-card.md: current
  • docs/capy-install.md: current (the R75 paragraph and the trailer grammar agree)
  • docs/troubleshooting.md: current (the upgrade-skipped and pin-unreasoned fixes agree)
  • docs/unattended.md: current (the merge-not-rebase rule; both new links resolve)
  • changelog.d/fix-behind-trailer-and-rebase-docs.md: current (fragment; not edited, since the parent owns it)

Coverage debt: no new public surface. The behind= rule has reference coverage in docs/capy-install.md and docs/troubleshooting.md and how-to coverage in the Capy skill and lane card, so there are no gaps.

Diagram drift: none. No diagrams reference the changed entities.

Test plan

  • CI free suite (ci-reuse/free-tests, run 42643618481) at 8e64a8a, tree 5acd3a58cf44: green, carried by CI carry (36841 tests, 1654 files).
  • Every pull_request check at 8e64a8a: 41 success, 0 failed, 0 pending, 13 skipped. macOS (cso-macos-launcher, macos-named-regressions) and windows-smoke cleared the pregate's remote lanes.
  • Focused tests at 8e64a8a in this /ship run: 7 files (context-budget-ratchet, capy-skill-wrapper, parity-suite, troubleshooting-anchors, skill-size-budget, gstack-capy-install, prose-lint), 524 pass, 0 fail.
  • Lane checks at 8e64a8a: 13 guard and focused files, 625 pass, 0 fail.
  • Trial merge with Run checks for files that still name deleted tests (#3536) #4158 (45701d4): clean, typecheck 0 errors, 432 pass across 3 files.
Agent notes

Refs GST-2136

Approvals

Approved: yes (record r-22f09787b801). The full approval record stays private.
Plan: exempt: bug fix
Plan check: exempt bug fix

REVIEW_LOOP: passes=2 blocking_found=1 deferred=0 noted=5 fixed=0 scope=frozen unrecorded=1 ledgers_read=4 fix_checks=2 dispatches=3 est_input_tokens=13655
Gate edits: none detected (1 listed, 1 read).
Review-loop exception: accepted by Captain GStack Minder (GSTA-36) 2026-11-09 via a-8336e5886c5d: one scoped fix-check past the round-2 cap for p2/outside-voice#1, a pin with a recorded reason holds (review_loop_grant 8e64a8a on #4224, Captain grant a-7b7ca6b68359) (fix-check at 8e64a8a, 4 findings)

Review: pass 1 light (specialist-batched, no findings; one core note at bin/gstack-capy-session:244). Pass 2 scoped after a CI repair (red-team and fix-check, no findings). Step 11 at 0e737b3: adversarial-native 4 Low notes, outside voice openai/gpt-6.1-sol 1 blocker (p2/outside-voice#1). Granted fix-check at 8e64a8a (p3): 4 INFORMATIONAL, 0 CRITICAL. Step 11 was not rerun after the fix-check: its plan listed no voices (ADVERSARIAL: skipped (review plan)).

C8 declined: the sentinel polling in CLAUDE.md and AGENTS.md is right for Claude Code, where a detached eval has no callback. eval:watch is retired, and the only other mechanism, bun run scripts/eval-bg.ts status, is already named there.

Classifier: DOCS_ONLY: no (bin, lib and test files changed), so CI ran in full.

Paid evals: none run. eval:select's selection was over the $10 per-PR cap.

gstack: ok 1.98.0.0 for=ship (behind=1 (latest: 1.98.0.0); fix: bash /home/user/.capy/drive/user-garry-tan/skills/gstack/scripts/install.sh --for ship)

{
  "schema_version": 1,
  "pr": 4224,
  "head": "8e64a8a4f5a7ef2607a8ada4c00aff3c75366d6d",
  "version": "1.98.0.0",
  "base": "main",
  "gate": {
    "free": {
      "pass": 1654,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "free",
      "run": 42643618481,
      "attempt": 1,
      "tree": "5acd3a58cf44d1c79774ae9daebe6d7f1a3217f6"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "5acd3a58cf44d1c79774ae9daebe6d7f1a3217f6",
  "product_patch_id": "1f6eadaf6a74303280935e62e38897a6e1d58515",
  "gstack_version": "1.98.0.0",
  "review_depth": {
    "depth": "light",
    "class": "code",
    "runtime_lines": 25,
    "rules": "66e5174161eecc2c",
    "base": "324135dfb150dc6a756801184a39f218b23b77c4",
    "registry": "324135dfb150dc6a756801184a39f218b23b77c4",
    "gate_scan": {
      "tagged": 0,
      "head": "8e64a8a4f5a7ef2607a8ada4c00aff3c75366d6d"
    },
    "reasons": [
      "runtime=25"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @5acd3a58cf44 (8 checks, current for 8e64a8a4f5a7)",
  "requires_remote": [
    "free-tests.yml/cso-macos-launcher: https://github.com/garrytan/gstack/actions/runs/42643618481/attempts/1",
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/42643618481/attempts/1",
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/42643619456/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=5acd3a58cf44 tests=36841 skipped=90 runs=42643618481/1 profiles=ci-reuse/free-tests heads=8e64a8a4f5a7 verified=2026-11-09T15:41:19.332Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, capy/skill/gstack (the 9 committed files 324135d..8e64a8a and their cross-references)"
  },
  "review_loop": {
    "passes": 2,
    "blocking_found": 1,
    "deferred": 0,
    "noted": 5,
    "fixed": 0,
    "scope": "frozen",
    "fix_checks": 2,
    "rounds": 4,
    "est_input_tokens": 13655,
    "unrecorded": 1,
    "ledgers_read": 4,
    "dispatches": {
      "specialist-batched": 1,
      "red-team": 1,
      "fix-check": 1
    }
  },
  "review_loop_exception": {
    "accepted_by": "Captain GStack Minder (GSTA-36)",
    "date": "2026-11-09",
    "via": "a-8336e5886c5d",
    "reason": "one scoped fix-check past the round-2 cap for p2/outside-voice#1, a pin with a recorded reason holds (review_loop_grant 8e64a8a on #4224, Captain grant a-7b7ca6b68359)",
    "fix_check": {
      "head": "8e64a8a4f5a7ef2607a8ada4c00aff3c75366d6d",
      "findings": 4
    }
  }
}

Open in Capy

…ST-2136)

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

trunk-io Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 2 commits November 9, 2026 15:05
…te (GST-2136)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…gelog fragment (GST-2136)

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