[theCodeDrift]

Makes stacked, merging forward, every layer green the default delivery shape, landed with gh stack merge.

• gh stack merge is all-or-nothing in both directions. It lands the whole stack at once, so units that are only correct together still reach main together, and one red layer blocks the whole stack. "Only correct together" is therefore a reason to put those units in the same layer, not a reason for a red intermediate one. Make the change that cannot be split into one layer, and move everything that is correct without it below.
• Each branch is verified before pushing (typecheck, lint, full suite), not only the tip.
• Merging down is reserved for vendor upgrades. There the engine bump goes red in its own layer, so a reviewer sees what the new version broke, and the layers above it make it green.
• A machine-generated bump merges laterally. When the upgrade workflow opens the bump PR, cut a new branch from its head, target main, and add the fixes there, so the bump and its repair land atomically instead of being merged down into a machine-generated branch.
• The changeset and archive guidance is adjusted for stacks that land at once: the changeset still lives on the bottom branch, and growing it per layer becomes a review preference.

Prompted by #583–#586, where a red intermediate layer would have blocked gh stack merge. That stack has been regrouped to be green at every layer.

No changeset: this changes contributor guidance only.

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 1m 56s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contained no prior review threads, reviews, or inline comments for this PR (only the triggering @claude /review comment), so this is the first review of this PR — the whole diff was assessed fresh.

Scope: docs-only change to AGENTS.md, restructuring the "Stacked PRs" section to make stacked-and-merged-forward (via gh stack merge) the default delivery shape, with merge-down reserved for vendor upgrades, plus corresponding updates to the changeset-growing guidance.

Findings:

• AGENTS.md:123 — [New] The new sentence "Merge down only for a vendor upgrade, or a lateral merge into the stack" introduces a "lateral merge" concept that is never defined anywhere in the document. The table above it and the "Landing a vendor-upgrade stack" section below only describe merging down; there's no section explaining what a lateral merge is, when it would be used instead of a down-merge, or how to execute one. Posted inline.

Consistency checks that passed:

• gh stack merge is an existing, previously-documented mechanism in this repo (used the same way in openspec/changes/archive/2026-10-08-feedback-channels/proposal.md and 2026-10-21-stdout-only-colour/proposal.md), so the new table row and "Landing a stack" section aren't referencing an invented command.
• The table's "the tip archives the change" (forward) and the later archiving paragraph ("a change is archived exactly once, on whichever PR is the tip") agree.
• The new "Landing a stack" / "Landing a vendor-upgrade stack" headers and the gating text ("This applies only to a stack whose bottom layer is red by design") are internally consistent with the revised table and the "Merge forward... / Merge down only..." paragraphs above.
• The changeset section's new framing (growing per-layer is a review preference, not a correctness constraint, since both landing paths are atomic) is consistent with the rest of the PR's model.

No other correctness, security, or clarity issues found in the diff.

[theCodeDrift]

Re: @github-actions — "Claude finished @theCodeDrift's task in 1m 56s — Review complete…"
#588 (comment)

The one finding (undefined "lateral merge" at AGENTS.md:123) is fixed in da99753 by dropping the phrase. The branch was also rebased onto current main.

— AI Coding Agent