Repository navigation
docs: document the standing-PR body as an interface, add agent guidance - #619
Open
goosewobbler wants to merge 6 commits into
Open
goosewobbler wants to merge 6 commits into
goosewobbler wants to merge 6 commits into
Conversation
Covers items 1–4 of #549, rescoped away from leading with a skill. The standing-PR body carries machine-read regions that decide what ships, and nothing in docs/ said so. An agent — or a person — tidying the body, reflowing the markdown, or stripping HTML comments changes the release, and it looks fine in review because the prose still reads correctly. docs/standing-pr-body.md is the reference: every marker, what an edit does, and what is bot-owned. Serves humans as much as agents. The two access rules differ in a way worth stating plainly — selection, channel, and release-control labels are reverted when an unauthorized actor changes them (given ci.standingPr.authorization), while release-notes prose has no author check at all on the publish path. That is defensible, since prose doesn't decide what version of what package reaches a registry, but it should be known rather than discovered. docs/agents.md carries the paste-ready AGENTS.md snippet, the propose → approve → publish boundary with the enforcement named at each step (rulesets gate the merge, OIDC scopes the credential, advisory text gates nothing), and the positioning section on why a generated release script is the wrong thing to own. No SKILL.md. Per the rescoped issue that ships only if these prove insufficient against a real consumer, since releasekit is commit-first on conventional commits — agents already know that format, unlike the bespoke file changesets requires. Every marker, the preview-notes label default, and every cross-link verified against source rather than written from memory. Closes #549. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FADRmu9uhtCk3StMoqwV27
Contributor
|
Standing release PR: #614 · v0.42.0 queued (4 packages) · open 68d 23h 29m · ✅ ready to merge Release Preview — v0.41.2 → v0.41.3
These changes will be added to the release PR (#614) when merged: Changelogmonorepo 0.41.2 → 0.41.3
After merge — predicted release
Updated automatically by ReleaseKit |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
From Greptile review of #619, and a correctness bug in the section where correctness matters most. The safety boundary claimed CI authenticates with short-lived OIDC tokens "rather than a long-lived token", and that the publishing credential exists only for a job's duration. Neither holds for crates.io: `hasCargoAuth` reads CARGO_REGISTRY_TOKEN, a repository secret that outlives every job. npm and pub.dev do support OIDC. Reads accurately now: OIDC where the registry supports it, with crates.io called out as the exception and the handling a long-lived secret needs, pointing at #546 where OIDC for it is tracked. The claim that does hold for every registry — nothing an agent does reaches one without a human merge — is stated on its own rather than resting on the credential lifetime. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FADRmu9uhtCk3StMoqwV27
- Notes markers are always keyed per package in the standing PR. - Checklist/channel edits apply only when the next update rebuilds the PR; document the sync, lockstep, primaryPackages and channelToggle caveats and the lowercase-[x] / same-line glyph rule. - Stop telling agents to run `standing-pr update`; point them at the workflow instead. - The merge gate is the review ruleset on the base branch, not the release-branch lock (also fixed in ci-setup.md). - Reword manifest validation without overclaiming tamper-resistance. - Define the gated release-control labels, note bots count as authorized, and list the conditions the "human merge" boundary needs. - Qualify external claims (crates.io trusted publishing, pub.dev OIDC, incident list, npm classic-token revocation). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HQN3v9Z4f1mu3xK4Z7K44e
…t guidance Third-review follow-ups: - A sync release without version.mainPackage renders one notes region keyed `monorepo`, and edits to it are currently discarded (#656). Say so in the marker table and the notes section, with the workaround. - Drop "of the selection" from the manifest's tamper-proof caveat, and link agents.md to the reference instead of repeating the checks. - Unticking a primary keeps packages another selected primary needs. - Replace standing-pr-body's "For agents" list, which duplicated the agents.md snippet, with a pointer to it — one list, no drift. - Turn the notes-edit loss cases into a list. - ci-setup: add the Actions-can-approve caution to the review ruleset step (#653), and fix the broken "combining strategies" anchor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HQN3v9Z4f1mu3xK4Z7K44e
…step wording Fourth-review follow-ups: - Remove the "set mainPackage" workaround for #656: it also narrows the sync changelog to commits touching that package, silently dropping release-note entries. - Marker table: a sync release without packageSpecificTags has a single region keyed by mainPackage, else `monorepo` — not one per package. - The fixed/linked "untick is ignored" rule holds in the flat and granular lists; in streamlined mode a group with no declared primary can currently be split (#657). - Unticking a primary keeps members it shares with another selected primary (not "packages another primary needs"). - Drop "The manifest, not the body, is authoritative for these." - AGENTS.md snippet: add the "don't reformat the body" rule and "only when asked" for notes, which the removed duplicate list carried. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HQN3v9Z4f1mu3xK4Z7K44e
Fifth-review nits: streamlined mode can split a lockstep group in more than one way (#657), and the manifest's tags are checked against the validated versions rather than matched one-for-one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HQN3v9Z4f1mu3xK4Z7K44e
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Covers items 1–4 of #549, which was rescoped away from leading with a skill.
The gap
The standing-PR body carries machine-read regions that decide what ships, and nothing in
docs/said so. Standing PRs are referenced across the docs, but no page stated where a human or agent may write, what an edit does, or what is bot-owned.An agent — or a person — tidying the body, reflowing the markdown, or stripping HTML comments changes the release. It looks fine in review, because the prose still reads correctly.
docs/standing-pr-body.mdThe reference: every input marker (the keyed
releasekit-notes:<pkg>regions,rk-sel,rk-pre,rk-grad, thereleasekit-manifestcomment), what an edit to each does, and the bot-owned markers it will overwrite. Written for humans as much as agents. It covers when a checklist or toggle change actually takes effect (only once the bot rebuilds the PR — merge after the rebuilt body shows it), the cases where the checklist doesn't apply as-is (sync releases; fixed/linked members in the flat and granular lists; non-primary members in streamlined mode), and the ways a notes edit can be lost — including two current gaps found while writing it, now tracked as #656 (notes edits discarded in a sync release whose region is keyedmonorepo) and #657 (streamlined mode can split a lockstep group).It also states plainly a distinction that's currently only discoverable by reading the source — the two access rules differ:
ci.standingPr.authorization): an unauthorized change is reverted, with a comment explaining why. The doc lists exactly which labels are gated and which aren't.publishFromManifestreads the region from the live PR body unconditionally.That's defensible, since prose doesn't decide what version of what package reaches a registry. But it should be known rather than discovered. Neither substitutes for the branch rulesets: the merge gate is a review-required ruleset on the base branch.
docs/agents.mdstanding-pr updatethemselves (it resets and force-pushes the release branch). The reference doc points to it rather than keeping a second copy.Also in
packages/release/docs/ci-setup.md: corrects the "ruleset on the release branch" wording, adds a caution that the template's required Allow GitHub Actions to create and approve pull requests setting lets workflow tokens approve PRs (#653), and fixes a broken anchor. Anddocs/rust.md: it's releasekit, not crates.io, that lacks OIDC (#546).No SKILL.md
Deferred per the rescoped issue: it ships only if these prove insufficient against a real consumer (wdio-desktop-mobile, zubridge). The sampo precedent doesn't transfer — sampo needs a skill because changesets requires authoring a file in a bespoke format, while releasekit is commit-first on conventional commits, which agents already know.
Verification
Every marker, label, trigger, and behaviour described was checked against the source on this branch, and every cross-link and anchor resolves. Review rounds caught and corrected: the notes-marker form, when checklist edits apply, the agent advice to run
standing-pr update, which ruleset is the merge gate, and over-broad claims about manifest validation and the agent boundary.Part of #549 — the validation step (trying these against a real consumer before deciding on a SKILL.md) remains.
🤖 Generated with Claude Code
https://claude.ai/code/session_01FADRmu9uhtCk3StMoqwV27
https://claude.ai/code/session_01HQN3v9Z4f1mu3xK4Z7K44e