[habdelra]

Important

Merge order: cardstack/boxel#6587, then this.
This documents the rule that cardstack/boxel#6587 adds, so merge it after that one. It changes only docs, so nothing is deployed.

Merges after: cardstack/boxel#6587

Boxel now lints this whole repo at the revision it pins, because production deploys boxel with this repo at that revision. A boxel change that breaks a file here pins the head of the pull request here that fixes it. That pull request merges right after the boxel one, with a merge commit, so the pinned commit is on main.

AGENTS.md and the catalog-deploy skill now say so, with the steps for that kind of pair. Boxel's catalog-pairing skill has the full procedure.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Staging Submissions Preview

This PR's content is pushed to the staging submissions realm: https://realms-staging.stack.cards/submissions/

Changed folders:

• .claude/

Updated at 2026-10-07 02:36:01 UTC for commit 7033fab. Shared realm: only this PR's changed files are pushed; files touched by multiple PRs reflect whichever pushed last, and deleted files are not removed.

[habdelra]

[Claude Code 🤖] I checked each claim in the two doc changes against what the paired boxel pull request's workflows and scripts do, and against this repo's deploy-production.yml. I also checked the pairing declaration. I did not review the boxel code itself.

No blocking issues. Two statements are factually wrong and should be fixed before merge: which check enforces approval, and the deploy's refusal message and recovery steps. Both are inline. The pairing declaration is valid. The Merges after: line sits outside the callout, the boxel side names this PR back with Merges before:, and both target main from same-repo branches.

1. Name Lint Catalog, not Catalog Test Subset, as what holds the boxel PR until this PR is approved (inline on AGENTS.md, step 2).
2. Quote the refusal a squashed pin actually gets, and add deploying main by hand to the recovery (inline on catalog-deploy/SKILL.md).
3. The same wording is in the paired boxel pull request: the README bullet, and the catalog-pairing skill's Catalog Test Subset paragraph and step 4. Fix it there too, so the two repos don't disagree.

Follow-up, not this PR: the merge commit is a convention that nothing enforces. This repo allows squash and rebase merges. Once the catalog PR has merged, boxel's checkPin passes a squashed pin, because merged is set and it only runs when the manifest changes. So a squash shows up only when the production deploy refuses. A guard would close that gap. Two options: a Lint Catalog or --check-pin step on boxel main pushes that requires the pin to be an ancestor of catalog main, or allowing only merge commits here. That deferral needs a ticket.

[habdelra]

[Claude Code 🤖] This puts the approval gate on the wrong check for the usual case. Please name Lint Catalog as the gate. In boxel's checkPin (sync-test-subset.ts), pinVerdict only runs once a subset file at the pin differs from catalog main. A fix that touches only non-subset files, which is what this rule is mostly for, leaves changed empty. The check then passes on the first early return, whether this PR is a draft, unapproved or stacked. What actually holds the boxel PR until this PR is approved is Lint Catalog's catalog-main verdict (mainVerdict), because the boxel change adds errors to catalog main. pinVerdict also refuses while the boxel PR has an unmerged Merges after: pair, and the sentence leaves that out.

Suggested wording: "Boxel's Lint Catalog lets the boxel PR merge only while this PR is open, ready for review and approved, and neither PR is stacked. When this PR changes a file the manifest lists, boxel's Catalog Test Subset check also requires the pin to be this PR's head."

The paired boxel pull request's README bullet and catalog-pairing skill paragraph use the same wording, so they need the same fix. Non-blocking, but a reader who trusts it will expect a red Catalog Test Subset that never shows up.

[habdelra]

[Claude Code 🤖] Fixed in e053603. Step 3 now names Lint Catalog as what holds the boxel PR until this PR is approved and neither PR is stacked. It says Catalog Test Subset applies the same terms only when this PR also changes a file the manifest lists. boxel#6587's catalog-pairing skill and README now say the same, in 297338559f.

[habdelra]

[Claude Code 🤖] Two things here are wrong for this case, and both should change before merge.

1. Wrong message. The refusal a squashed or rebased pin gets is not "isn't an ancestor of". This repo's deploy-production.yml "Resolve the revision" step runs first. It compares $sha...main, and when the pin isn't on main it fails with <sha> isn't on catalog main. Deploy a revision on main. before catalog-deploy-check.ts ever runs. The "isn't an ancestor of" message comes from catalog-deploy-check.ts, and only when production's current catalog has diverged from the target. A reader searching for the quoted text won't find it in the failed run.
2. Incomplete recovery. "Re-pin boxel … then deploy again" means a boxel PR plus another boxel release. Until then, production runs the new boxel against the old catalog, and the after-release job is red. The quicker fix is to run Deploy to production by hand with revision empty. main already has the squashed fix, and the Merges after: hold is released because production now runs the boxel PR. The re-pin is still needed, so the next boxel release doesn't refuse again.

Suggested:

Suggested change

Boxel's production deploy ships this whole repo at the revision boxel pins, so boxel lints the whole repo at the pin against every boxel change, not only the files its test subset lists. A boxel change that breaks a file here pins the head of the pull request here that fixes it. That pull request says `Merges after:` the boxel one, and merges right after it with a merge commit, so the pinned commit is on `main` when production deploys it. A squash or a rebase leaves the pinned commit off `main`, and the deploy refuses with "isn't an ancestor of": re-pin boxel to a `main` commit that has the fix (`pnpm --dir packages/catalog catalog:test-subset --bump`), then deploy again.

Boxel's production deploy ships this whole repo at the revision boxel pins, so boxel lints the whole repo at the pin against every boxel change, not only the files its test subset lists. A boxel change that breaks a file here pins the head of the pull request here that fixes it. That pull request says `Merges after:` the boxel one, and merges right after it with a merge commit, so the pinned commit is on `main` when production deploys it. A squash or a rebase leaves the pinned commit off `main`, and the deploy refuses with "isn't on catalog main". To recover, deploy `main` by hand (it has the fix), then re-pin boxel to a `main` commit that has the fix (`pnpm --dir packages/catalog catalog:test-subset --bump`) so its next release doesn't refuse again.

The paired boxel pull request's catalog-pairing skill quotes the same wrong message in its step 4.

[habdelra]

[Claude Code 🤖] Fixed in e053603, with boxel#6587's 297338559f. A squashed or rebased pin no longer needs a re-pin: boxel's lockstep deploy now deploys the pull request's merge commit in place of the pinned head. The skill now quotes the real by-hand error (" isn't on catalog main. Deploy a revision on main.") and points to deploying main's head, which already has the fix.

[habdelra]

[Claude Code 🤖] On the two review-body points. The same wording in boxel#6587's README and catalog-pairing skill is fixed in 297338559f. The follow-up for enforcing a merge commit isn't needed: boxel#6587's lockstep deploy now maps a squashed or rebased pinned head to its pull request's merge commit, so any merge method deploys the fix and nothing is left to enforce.