docs: name the mechanism — branches: [main] matches a stack's eventual target

`branches: [main]` reads as "only PRs whose base is main," and filtered that way
when a PR had one base. Under GitHub's stacked-PR support a stacked PR targets
`main` eventually, so the filter matches the eventual target and these workflows
run on mid-stack PRs too — which is why #73, #80, and #81 each produced a failing
`Require a changeset` run with an `openspec/partition-engine-*` base.

That makes the base-ref guard required rather than defensive, and generalizes: a
workflow whose correctness depends on "is this the PR that merges to main" has to
establish that itself. Corrects the OpenSpec archive-check section too, which
told readers a stacked PR would not run that check at all.

Author: thecodedrift

.agents/skills/iterate-pr/SKILL.md

@@ -246,11 +246,11 @@ exactly once, at the END of the work — so a PR that still carries an in-progre
 change directory will fail this check. Archiving on an intermediate PR is wrong:
 it would remove the change docs before the implementation PRs above it merge.
 
-Note the workflow's trigger is currently `pull_request.branches: [main]`, so it
-only RUNS on PRs whose base is `main`. A stacked PR based on another feature
-branch won't run (or fail) this check at all — so there is nothing to ignore
-there. The check matters for PRs that target `main`: typically the bottom of a
-stack, plus any PR later retargeted to `main` as the stack merges down.
+The workflow's trigger is `pull_request.branches: [main]`, but do NOT read that
+as "it only runs on PRs whose base is `main`." Under GitHub's stacked-PR support
+a stacked PR targets `main` eventually and the filter matches that eventual
+target, so this workflow runs on mid-stack PRs as well. Expect to see the check
+on every PR in a stack and decide from stack position, not from the `on:` block.
 
 When the archive check does run and fail, decide ONE thing before treating it as
 actionable: **is this PR the last in the chain (the tip)?** A PR is the tip when
@@ -292,6 +292,14 @@ Mid-stack PRs bypass the check on their base ref. If you see one failing it,
 look at that guard rather than reaching for the label, which would wrongly
 record the change as shipping no release note.
 
+**Do not read `on: pull_request: branches: [main]` as "this only runs on the
+bottom PR."** Under GitHub's stacked-PR support a stacked PR targets `main`
+eventually, and the filter matches that eventual target — so these workflows run
+on mid-stack PRs too. A workflow that must act only on the PR merging to `main`
+has to establish that from the base ref or its stack position. When judging
+whether a check "should even be running here," check the stack rather than the
+`on:` block.
+
 ### Never leave a PR on red
 
 **No PR merges with failing tests, including mid-stack.** "Merging down" changes

.github/workflows/require-changeset.yml

@@ -44,19 +44,19 @@ jobs:
           # papered over with a `skip-changeset` label, which would wrongly
           # record "this change ships no release note."
           #
-          # `on: pull_request` with `branches: [main]` is documented to filter on
-          # the PR's BASE branch, which should make this unreachable. It was not:
-          # PRs #73, #80, and #81 — bases `openspec/partition-engine-*`, never
-          # `main` — each produced a failing `Require a changeset` check run
-          # (e.g. run 30786954198, event `pull_request`, head
-          # `openspec/partition-engine-2-dispatch`, associated PR #80 with a
-          # feature-branch base). A workflow that never triggers produces no
-          # check run at all, so those runs are the evidence.
+          # This guard is required, not belt-and-braces. `branches: [main]` reads
+          # like "only PRs whose base is main," and that is how it filtered when
+          # a PR had exactly one base. Under GitHub's stacked-PR support a PR in
+          # a stack is understood to target `main` *eventually*, so the filter
+          # matches on the eventual target and the workflow runs on mid-stack
+          # PRs too. Observed here: #73, #80, and #81 — bases
+          # `openspec/partition-engine-*`, never `main` — each produced a failing
+          # `Require a changeset` check run (e.g. run 30786954198, event
+          # `pull_request`, head `openspec/partition-engine-2-dispatch`).
           #
-          # Treat this as a defensive guard: if the trigger filter behaves as
-          # documented it costs one string comparison, and where it does not, it
-          # is what keeps a mid-stack PR from being told to add a second
-          # changeset.
+          # So `branches:` no longer scopes a workflow to the bottom of a stack.
+          # Any job whose correctness depends on "is this the PR that merges to
+          # main" has to establish that itself, as this one does.
           if [ "$BASE_REF" != "main" ]; then
             echo "Base is '$BASE_REF', not 'main' — mid-stack PR, so the bottom PR of the stack carries the changeset."
             exit 0

CLAUDE.md

@@ -93,7 +93,9 @@ Note how this interacts with the archive gate (see the OpenSpec archive check be
 - **The changeset belongs on the bottom PR**, the one that targets `main`. That is the only place it can live: a changeset added on the tip is invisible to the bottom PR's diff, so the check would fail on the PR that actually merges.
 - **Mid-stack PRs bypass the check**, because the base branch is not `main`. They inherit the base's changeset rather than adding one, so there is nothing for the check to find. **Do not label them `skip-changeset`** — the label records a deliberate "this change ships no release note," which is false here, and the bypass already handles it.
 
-The bypass is an in-step check on the base ref. `on: pull_request` with `branches: [main]` is documented to filter on the base branch, which should make that redundant — but it did not hold here: #73, #80, and #81 all produced failing `Require a changeset` check runs with `openspec/partition-engine-*` bases, and a workflow that never triggers produces no check run at all. Keep the guard, and if you see a mid-stack PR failing this check, look there rather than reaching for the label.
+The bypass is an in-step check on the base ref, and it is load-bearing. **`branches: [main]` no longer means "only the PR whose base is `main`."** Under GitHub's stacked-PR support, a PR in a stack is understood to target `main` eventually, so the filter matches on that eventual target and the workflow runs on mid-stack PRs as well — observed here on #73, #80, and #81, all with `openspec/partition-engine-*` bases.
+
+The general rule that follows: **any workflow whose correctness depends on "is this the PR that merges to `main`" must determine that itself** — from the base ref, or by resolving stack position — and cannot lean on the `on:` filter to scope it. If you see a mid-stack PR failing this check, look at that guard rather than reaching for the label.
 
 Put the changeset at the base and every branch above inherits it, since a child contains its ancestors' commits.