[ilanh]

Closes #79

Infrastructure for building openshell-annotate against the next OpenShell release before it ships stable. The openshell-next branch it maintains already exists (draft PR tracking #80).

Branch model

• openshell-next is the one long-lived branch: main plus the OpenShell pin on the newest upstream tag, prereleases included (now v0.1.8-pre.3), plus fixes that only make sense there. Fixes that are also valid on main's pin go to main first and reach the branch through the daily merge.
• It only moves forward through merges (no rebase or force push). To promote it, squash-merge the tracking PR once OpenShell ships stable (docs/RELEASING.md).

Automation: .github/workflows/openshell-next.yml (daily 04:17 UTC + workflow_dispatch with tag / report inputs)

1. Merges origin/main into openshell-next with a signed-off merge commit. If both sides moved the pin, it keeps the newer tag and re-resolves Cargo.lock. Any other conflict stops the run without pushing and is reported.
2. Moves the pin when upstream has a newer tag and commits as github-actions[bot] with a Signed-off-by line.
3. Runs fmt, clippy -D warnings, cargo test --locked and gen-docs.sh --check in the same job.
4. Pushes the branch, even when the tests are red (the branch mirrors upstream), then runs gh workflow run ci.yml --ref openshell-next. GITHUB_TOKEN pushes trigger no workflows, but workflow_dispatch is allowed, so check / audit land on the tracking PR's head commit. For this, ci.yml gains a workflow_dispatch trigger.
5. Comments on the openshell-next-labelled issue (or creates it) when the pin moved, the branch was created, or the merge or tests failed. The comment has the old and new tag, upstream release and compare links, the result, a log tail and the run link. A stable tag adds the promotion note. It never opens PRs: the repo doesn't let Actions create PRs, and the tracking PR already is the bump PR.

• Permissions: top-level contents: read. The job has contents: write, issues: write, actions: write and pull-requests: read. Only GITHUB_TOKEN is used.
• Actions are SHA-pinned (checkout v7.0.1, cache v4.3.0, the same SHAs release.yml and the composite actions use), with concurrency: openshell-next and no cancel.

Scripts

• scripts/openshell-tags.sh: latest / latest-stable / list / pinned / newer A B / is-stable A. It uses release order (stable vX.Y.Z > vX.Y.Z-pre.N), ignores dev and vm-runtime, and is portable. OPENSHELL_TAGS overrides the list for offline runs.
• scripts/openshell-next.sh: bump <tag> (both crates, comment, cargo update -p for both), update [<tag>], sync [<ref>].
• scripts/upstream-compat.sh now uses the tag script and repoints both crates. Before, openshell-policy (the gateway validator) stayed on the old tag, so compat runs never tested the new validator. It also uses portable sed, so it runs on macOS.
• upstream-compat.yml also runs on every push to main (docs-only changes skipped) and stays non-blocking (continue-on-error for push/PR). Its actions are now SHA-pinned.

Proposed, not applied

.github/rulesets/protect-openshell-next.json blocks deletion and non-fast-forward pushes on openshell-next. It also stops delete_branch_on_merge from deleting the branch when the tracking PR is squash-merged. It has no PR or status-check rules, so the bot can push. Apply it with gh api -X POST repos/ilanh/openshell-annotate/rulesets --input .github/rulesets/protect-openshell-next.json.

Docs

• docs/DEVELOPING.md, §4: new "Tracking the next OpenShell release", plus updates to the compat section. §8 also changed.
• docs/RELEASING.md: new "Promoting openshell-next when OpenShell ships stable".
• CONTRIBUTING.md (the branch exception and the label), the AGENTS.md bullet and doc-mapping row, scripts/labels.sh (the openshell-next label) and CHANGELOG.

Verified (macOS)

• actionlint is clean. shellcheck is clean on the new and changed scripts. gen-docs.sh --check and gen-actions-docs.sh --check pass.
• openshell-tags.sh runs against the real NVIDIA/OpenShell tags: latest = v0.1.8-pre.3 and latest-stable = v0.1.7. Ordering edge cases pass (pre vs stable, v0.1.10 vs v0.1.9, junk tags).
• openshell-next.sh was tested in a scratch clone with real tags: update v0.1.7 → v0.1.8-pre.3 and then a no-op. sync handles a pin conflict both ways (keeps the newer tag) and aborts with exit 3 on a README conflict.
• I ran the report step's bash with a stubbed gh, both for the stable-tag + failing-tests comment and for the quiet no-change path.
• scripts/upstream-compat.sh latest-prerelease (both crates at 53b8eec2) reports ✅ compatible.