feat(release)!: publish next from the release-PR hook and drop the post-green verdict

[Vivswan]

Before / After

Before: a check of our own decided every next publish, on every green push.

push to main -> ci.yml -> all-green -> post-green.yml
                                       |- build:        package-commit, latest
                                       `- publish-next: npm-verdict next
                                             walk the merges since next's source over the shipped surface
                                             publish <version> | skip "no shipped file changed since ..."
                          release -> update-release-pr.yml (prs_created)
                                       `- anchor

After: release-please's refresh of the release PR is the publish signal; nothing of ours decides.

push to main -> ci.yml -> all-green -> post-green.yml
                                       `- build: package-commit, latest
                          release -> release-please: release notes changed?
                                       |- no  (test, docs, chore, build, ci) -> no refresh, no hook call, no publish
                                       `- yes (feat, fix, perf, revert, !)  -> refresh the release PR
                                            `- update-release-pr.yml (prs_created)
                                                 |- anchor
                                                 `- publish-next: guard on npm state -> npm publish --tag next -> confirm

The skip notice, before and after:

before  ::notice::no shipped file changed since 2.0.1-main.440.20260901.g1111111 (source 1111111): no merge to main in 1111111..abc1234 touches package.json, lib/pkg/, src/, ...
after   (no verdict: a push that refreshes no release PR never reaches the publish job)
        the two notices left are registry safeties, never decisions:
        ::notice::2.0.1-main.447.20260922.gabc1234 is already on the registry
        ::notice::the registry already holds 2.0.1-main.448.20260922.gdef5678, whose source def5678 is a descendant of abc1234 on main, so this stale run publishes nothing (npm publish --tag next would move next back)

How

• .github/workflows/update-release-pr.yml: a publish-next job beside anchor, independent of it. The steps are the ones post-green held: OIDC check (same warning shape, naming this call), checkout of github.sha with full history and no persisted credentials, setup, setup-node with the registry, the npm floor, bun run build:lib, the publish step (guard, npm version, npm pkg delete scripts.prepare, npm publish --tag next), then npm-confirm. Same npm-publish lane. The header says why the publish lives here.
• .github/workflows/post-green.yml: the publish-next job is gone; build stays. Header fixed.
• .github/workflows/update-release.yml: two comments that named post-green's publisher now name the hook's.
• .github/scripts/release-pipeline.ts: the surface walk is deleted (NEXT_BUILD_INPUTS, shippedPaths, shippedChanges, ships, ALWAYS_PACKED, NextBase, mainChainOf, and the NEXT_BUILD_UNPACKED exclusion the closed PR removed). npm-verdict next stays as the pre-publish guard: version already on the registry, or a descendant's pre-release published, exits skip; a source the checkout cannot place is a notice. prerelease-version, npm-confirm, and everything about stable releases, packaging, and anchoring are untouched. Header table updated.
• test/scripts/release-pipeline.test.ts: the surface cases (docs-only skip, test-only skip, shipped paths, reverted and moved files, files-list shapes, build inputs) are deleted. The placement, no-backward (rerun, descendant published, unplaceable base), and confirm cases stay, with the wording they pin updated.
• test/docs/post-green-workflow.test.ts: the publish-job wiring and grant controls follow the job to the hook; the library-page claim check learns the third trigger (a release-PR refresh, by prs_created); a control pins that claiming next back on the green push fails; a new relation pins that the hook's checkout, publish, and confirmation all name github.sha.
• test/docs/npm-publish-workflows.test.ts: the pre-release publisher is read from the hook.
• docs/reference/library.md: the next row and bullets state the cadence. docs/upgrading/v2-to-v3.md: row and section 59 with a before/after. README.md: the library line points at Versioning.
• .github/actionlint.yaml, test/package-json.test.ts: comments naming the publisher.

Proof

• env -u NODE_OPTIONS bun run typecheck: clean.
• bun run knip: clean.
• bun run lint: clean.
• bun run lint:yaml: clean.
• bun test test/scripts/release-pipeline.test.ts test/docs --timeout 120000: 489 pass, 0 fail.
• bun test test/scripts/release-pipeline-build.test.ts --timeout 120000 (imports the changed script): 37 pass, 0 fail.
• bun run build:check: 13 generated files match their generators.
• Red-then-green does not apply: the change is a deletion of a decision plus a move of steps; the deleted behavior is listed in How, not pinned by a test.
• The hook cannot run locally. Its first real run is the next release-PR refresh on main; watch Update Release PR / anchor and Update Release PR / publish-next in that run.

Line accounting by kind

git diff --numstat origin/main...HEAD (the closed PR's commit is folded in, so its lines count here)

Kind	Files	Added	Deleted
Workflows	post-green.yml, update-release-pr.yml, update-release.yml	138	129
Script	release-pipeline.ts	40	240
Tests	npm-publish-workflows.test.ts, post-green-workflow.test.ts, package-json.test.ts, release-pipeline.test.ts	182	371
Docs	README.md, library.md, v2-to-v3.md	31	12
Lint config	actionlint.yaml	1	1
Total	12 files	392	753

Net deletion: 361 lines.

Reviewer note

• No check of ours decides a publish. The release-PR refresh is the signal, and it happens only when release-please's release notes change (always-update is off in release-please-config.json).
• npm-verdict next remains, as a safety on npm state: a rerun or a stale retry must not move next back. Its output shape is unchanged, so the publish step stays the twin of the stable publisher's and the shared-steps test keeps holding.
• The closed PR chore(ci): drop the never-packed exclusion now that src holds code only #401's deletion of NEXT_BUILD_UNPACKED is folded in.
• The hook needs no new input: inside a called workflow github.sha is the caller's sha, the push release-please judged, which the anchor job already relies on. The managed ci.yml is untouched.
• One factual correction to the design's wording: under release-please's default changelog sections, deps is not a releasable type. Dependabot lands build(deps) and ci(deps), both hidden, so a dependency bump alone refreshes no PR and publishes no next. The docs say so.
• After a release, next names the last pre-release below latest until the next cycle's first releasable commit; the docs say so.
• What the first live run must show: on a releasable merge, Update Release PR / publish-next runs npm publish --tag next (npm's output names the version) and the confirmation step ends with a settled notice; npm view @vivswan/github-settings-as-code@next then names that version. On a test-only or docs-only merge, no Update Release PR call appears in the run at all.
• Post Green in that same run shows only the build job, no publish job.

BEGIN_COMMIT_OVERRIDE
feat(release)!: publish next from the release-PR hook and drop the post-green verdict

The next pre-release publishes exactly when release-please creates or refreshes the release PR, and nowhere else: update-release-pr.yml, the hook the managed ci.yml calls on prs_created, gains a publish-next job beside anchor.
release-please refreshes the PR only when the release notes change (always-update is off), so a releasable commit publishes, a push of hidden types alone refreshes nothing and publishes nothing, and no check of the repository's own decides a publish.
post-green.yml loses its publish-next job and keeps the build job; the commit the hook publishes is github.sha, the caller's sha inside a called workflow, so ci.yml needs no new input.
release-pipeline.ts drops the npm-verdict next decision: the merge walk over the shipped surface, NEXT_BUILD_INPUTS, shippedPaths, shippedChanges, ships, ALWAYS_PACKED, and the never-packed exclusion list NEXT_BUILD_UNPACKED that matched nothing.
npm-verdict next stays as the pre-publish guard on npm state: a version already on the registry or a descendant's published pre-release exits skip, so a rerun or a stale retry never moves next back; prerelease-version and npm-confirm stay.
The pipeline test drops the surface cases and keeps the placement, no-backward, and confirm cases; the workflow-shape tests follow the publish job to the release-PR hook and learn the release-PR refresh as a trigger.
The README, the library page, and the v3 upgrading guide state the new cadence: a next build appears on a release-PR refresh, a merge of hidden types alone publishes nothing, and the guard keeps next from moving back.
END_COMMIT_OVERRIDE

[github-actions]

File size check

0 over a hard cap (fails), 31 warning(s).

File	Size	Tier	Cap
.github/scripts/release-pipeline.ts:6	156 chars	warn	150
.github/scripts/release-pipeline.ts:453	151 chars	warn	150
.github/scripts/release-pipeline.ts:1247	153 chars	warn	150
.github/scripts/release-pipeline.ts:1	34 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:449	14 comment lines	warn	10
.github/workflows/post-green.yml:29	153 chars	warn	150
.github/workflows/update-release-pr.yml:109	14 comment lines	warn	10
docs/upgrading/v2-to-v3.md	1276 lines	warn	1040
src/engine/layers.ts:217	157 chars	warn	150
src/flows/settings-write.ts:142	159 chars	warn	150
src/flows/settings-write.ts:30	11 comment lines	warn	10
src/flows/snapshot.ts:189	13 comment lines	warn	10
src/github/secret-scan.ts:42	11 comment lines	warn	10
src/schema.ts:186	153 chars	warn	150
src/schema.ts:197	176 chars	warn	150
src/sections/contract/errors.ts:14	14 comment lines	warn	10
src/sections/contract/module.ts:963	185 chars	warn	150
src/sections/contract/module.ts:627	12 comment lines	warn	10
src/sections/contract/module.ts:897	12 comment lines	warn	10
src/sections/secret_scanning_custom_patterns/compilable-form.ts:382	161 chars	warn	150
src/sections/shared/roles.ts:43	13 comment lines	warn	10
src/types.ts:16	156 chars	warn	150
test/docs/guides.test.ts:451	155 chars	warn	150
test/e2e/generators.ts	2633 lines	warn	2560
test/e2e/generators.ts:1703	166 chars	warn	150
test/e2e/generators.ts:1857	161 chars	warn	150
test/e2e/generators.ts:1666	12 comment lines	warn	10
test/engine/execute.test.ts:617	152 chars	warn	150
test/flows/merge-parity.test.ts:63	164 chars	warn	150
test/scripts/auto-fix-allowlist.test.ts:8	12 comment lines	warn	10
test/scripts/changed-sections.test.ts:416	154 chars	warn	150

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The production-only release trigger and npm OIDC publishing path cannot be verified end to end before its first live run.

Review effort: Balanced
Findings: None

What changed in this PR

Moves next npm publishing from every qualifying green push to release-please’s release-PR refresh hook.

Changes:

• Adds publish-next to the release-PR workflow and removes it from post-green.
• Simplifies the npm verdict to registry-state safeguards.
• Updates tests and documentation for the new cadence.

File	Description
.github/​actionlint.yaml	Updates publisher references.
.github/​scripts/​release-pipeline.ts	Removes shipped-surface decisions.
.github/​workflows/​post-green.yml	Removes next publishing.
.github/​workflows/​update-release-pr.yml	Adds the next publisher.
.github/​workflows/​update-release.yml	Updates shared-lane references.
README.md	Documents the new next cadence.
docs/​reference/​library.md	Revises versioning details.
docs/​upgrading/​v2-to-v3.md	Adds the cadence breaking change.
test/​docs/​npm-publish-workflows.test.ts	Tests the relocated publisher.
test/​docs/​post-green-workflow.test.ts	Tests trigger, grants, and wiring.
test/​package-json.test.ts	Updates workflow references.
test/​scripts/​release-pipeline.test.ts	Removes surface-verdict cases and retains safeguards.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

It changes the live npm publishing trigger and its first end-to-end execution cannot be exercised locally.

Review effort: Balanced
Findings: 1

Open (1)

• Incomplete possessive phrase in upgrade note · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

It changes the live npm release path, whose decisive workflow behavior cannot be exercised before the first release-PR refresh.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Incomplete possessive phrase in upgrade note

[Copilot]

Copilot review overview

🔵 Needs a closer look

The npm publishing trigger and OIDC workflow move require final human review and validation through the first live release-PR refresh.

Review effort: Balanced
Findings: None