[schlessera]

What changed

Install the pinned gh-stack skill once under .agents/skills/ and expose it to Claude Code through the same relative symlink convention as the other project skills. Document stacked PRs in contributor and agent entry points, the GitHub/testing process, the PR template, and the existing GitHub/work-issue procedures.

Why this shape

Stacks retain the existing per-PR proof, release milestone, contract, changeset and issue-completion requirements. Upper layers compare against their immediate parent. Stack merges need all included PRs inspected and their eventual main results reconciled. The installed gh stack merge --help confirms numeric targets prefer stack numbers and offers no matching-head flag; the imported skill now makes that ambiguity explicit.

Proof

• bun run check:pr --base origin/main: passed; 864 tests across 45 files, 0 failures.
• bun run lint after the final documentation edits: all gates clean.
• git diff --cached --check: passed before commit.
• Inspected all four installed skill files, identical original agent copies, the installed v0.2.1 CLI help, and existing workflow base selection. Verified the Claude skill symlink resolves to the canonical skill.
• Documentation/agent instructions only; no product behavior or new guard changed, so no behavioral mutation receipt applies. No package output changes or changeset required.
• Conflict refresh: merged main 53258a203d37ab32ae211c5f645cb32e2b3898d1, retaining both upper-stack parent selection and explicit candidate confirmation requirements in AGENTS.md. Then merged the non-conflicting base advancement 9506026705425653a40608395aa756cae2a344b2 and repeated preflight (862 passed, 0 failed). A second non-conflicting main advancement (b67b1b84e8ceacf8f0df3aee8f23f8bf32a91703, test cleanup only) was incorporated and preflight passed again (862 tests, 0 failures). Current head: a656beb6424929484e2bfb0cca61cbdfd589f805.
• Final head: f3a9b0fbc35e65016bb4f47625a74ebf0d796349; live base: 2e362cc12aa3d2bda38145b6da23d0ac232281b2. The additional base change updates browser shard cost tooling and merges without conflicts. Final local preflight: 864 passed, 0 failed.
• Maintainer exception (2026-10-16): merge without another confirmation refresh after repeated concurrent main advancement. Complete current-head hosted confirmation was not obtained. Earlier automatic runs contain successful category executions but were superseded/cancelled and are not claimed as complete final-head proof. Merged with a matching-head squash. Post-merge readback confirms 3fc6fea5e22304df2810348074c32b1983fbea46 on remote main, parent 2e362cc12aa3d2bda38145b6da23d0ac232281b2, and tree 86cd6eb93160937671127aed474acfc8c3e4ae2f equal to the inspected head tree. Release milestone 0.44.0 was retained. Automatic main-push CI started; its result is pending.

Checklist

• Focused local preflight/behavioral receipts and complete selected hosted proof passed; actual head/base/job checkout evidence is in Proof.
• Acceptance criteria from the request are met.
• The PR has the upcoming 0.44.0 milestone (registry latest is 0.43.1; live milestone 0.44.0 is the next minor).
• This changes nothing a package consumer can see.
• No personal data in the diff; leakage gate passed.
• No machine surface moved.
• Project docs reflect the change.

Anything left open

Complete current-head hosted confirmation is waived by the maintainer instruction above. Automatic post-merge main CI is checked separately.

[schlessera]

Observed gh-stack v0.2.1 append trap while extending native stack #2136 (2026-10-16): adopting an existing third branch with an existing draft PR succeeded locally. gh stack submit --auto --remote origin then pushed that branch, but left PR #2103 based on main instead of the current top branch. It printed both “cannot update while stacked” and the API chain-validation failure, yet returned exit 0. The authoritative stack still had only its original two members. This is partial failure, not successful publication.

Verified cause in upstream submit.go at v0.2.1: base correction is skipped whenever the local stack already has an ID, including an appended PR that is not itself stacked. This differs from creating a new PR with the correct base; it concerns an existing unstacked PR whose base needs correction.

Verified minimal recovery: after reading back every affected PR head/base/draft and confirming the appended PR belongs to no other stack, gh stack link 2136 2103 --remote origin corrected its base and appended it to the same native stack. link.go at v0.2.1 performs that correction before adding membership. Authoritative readback then showed exactly #2073 → #2072 → #2103, with the same native ID and frozen heads; all remained draft. No unstack, branch rewrite or ordinary PR merge was needed.

The imported skill already documents non-atomic submit behavior and link correcting existing PR bases; this observation records the narrower existing-PR append/exit-status trap. No frozen product branch was changed for this recovery.

[schlessera]

Native-stack CI integration finding filed as #2141 with exact frozen heads, authoritative declared bases, fresh root-main contract payload failures, synthetic predecessor-merge parents and the cancelled upper confirmation receipts. The existing guards are preserved. Native stack #2136 cannot currently obtain honest upper-layer proof under these workflows. Recovery removes only that grouping, keeps all PRs/branches/commits, restores upper drafts to ordinary main bases and reconstructs each own-only upper diff after its actual parent lands. No native stack merge bypass or inherited upper diff merge is authorized.