[P0 Release] Establish the protected npm `next` prerelease channel for v0.33.0-beta.1

[mohanagy]

Parent: #649
Milestone: v0.33.0-beta.1 — Trust Foundation
Blocks: the first beta publication
Does not block: ordinary issue implementation or draft PR review on next
Related broader release initiative: #676

Outcome

Publish immutable prerelease versions from exact reviewed commits on next.

• npm dist-tag next for prereleases.
• npm dist-tag latest preserved unchanged.
• GitHub releases marked as prereleases.
• Provenance and clean-install verification required.
• Publication unavailable until a human approves the protected environment.

Branch policy

Branch	Role
main	stable only (latest)
next	prerelease integration (next)
issue branches	created from next
roadmap PRs	target next
stable promotion	reviewed next → main PR

Version policy

0.33.0-beta.1
0.33.0-beta.2
0.33.0-rc.1
0.33.0

Every npm version is immutable. The next dist-tag moves between prerelease versions; latest moves only for stable releases.

Publishing requirements

• exact tag / package.json / CHANGELOG.md match;
• the tagged commit is contained in origin/next;
• complete protected validation on the exact tagged commit;
• npm Trusted Publishing via GitHub OIDC;
• provenance required;
• no fallback to an unreviewed workstation token;
• protected GitHub environment (npm-next);
• human approval before publish;
• pre-publication dist-tag snapshot;
• post-publication verification that latest did not move;
• exact-version and @next clean installation checks;
• packaged CLI smoke test run against a controlled workspace, not the repository checkout;
• GitHub prerelease receipt;
• documented rollback / remediation policy.

Current-state notes for the implementer

Verified at main = 3371ada8:

• .github/workflows/release.yml fires on v* and its regex accepts v1.2.3-beta.1. It creates a GitHub release without --prerelease, so a beta tag today would produce a stable-looking release. This must be separated.
• release.yml does not publish to npm. There is currently no npm publish workflow, so publish-next.yml is new and conflicts with nothing.
• package.json already defines publish:next as npm publish --tag next --access public — note the missing --provenance.
• Available scripts: typecheck, test:run, test:coverage, build, verify:pack-parity, registry:validate, release:verify, pack:dry-run.
• qualify:validate exists only on the [P0] Freeze the natural qualification corpus, independent rubrics, and stop rule #655 branch today. Once PR feat(qualification): freeze the independent qualification contract (#655) #681 lands on next, it becomes mandatory in the prerelease pipeline.
• Package name is @lubab/madar; bin is madar.

Explicit non-goals

• Do not publish during this issue's implementation PR.
• Do not create a beta tag before Phase 0 beta readiness.
• Do not publish stable latest.
• Do not publish MCP Registry metadata automatically for the beta.
• Do not merge next into main.
• Do not create another long-lived development branch.
• Do not permit publication between partial graph slices.

Acceptance criteria

• Prerelease workflow validates on the exact tagged commit and fails closed on any check error.
• Publication uses npm Trusted Publishing (OIDC) with id-token: write; provenance is attached.
• Publication requires approval in the protected npm-next environment.
• The tagged commit is proven to be an ancestor of origin/next; a tag outside next is rejected.
• Tag, package.json version, and CHANGELOG.md section match exactly.
• An already-published version is rejected rather than overwritten.
• latest is captured before publication and verified unchanged afterwards.
• Clean install of the exact version reports that version.
• Clean install of @next reports that version.
• The GitHub release is created with prerelease: true.
• No publish command can execute from push or pull_request events.
• Stable workflow rejects prerelease tags; prerelease workflow rejects stable tags.
• Rollback and incident response are documented (deprecate, dist-tag correction, never unpublish silently).

Release-readiness boundary

The pipeline may be prepared and merged into next before the beta is publishable. Three decisions are distinct and must not be conflated:

1. pipeline ready for review;
2. pipeline ready for merge into next;
3. beta ready to publish.

The beta remains blocked until Phase 0 beta readiness is met. In particular, do not publish during a partial graph-integrity migration. The graph sequence is #656 → #657 → #658 → #659; publishing after only #657 or #658 would ship artifact, integrity, and answerability behavior in an intentionally incomplete state.

Related tracking issue: #654 remains open, and roadmap PR merges remain blocked by it.

Agent handoff

The implementation agent must stop before publishing, tagging, merging, or changing repository environment settings. Repository and environment configuration is human-managed; the agent reports the exact required setup rather than applying it.

[mohanagy]

Remediation on PR #688: four review findings fixed, plus a lead-review correction

New head SHA: a7140d4f493827a7a92ceb2f5c688fcdd12467af (was 4f82365aa97e921dc07608bf87c3cfe0605510b2).

No tag and no npm package were published, and no GitHub release was created, at any point during this remediation. #688 stays a draft.

Findings fixed

• A — workflow_dispatch removed. The repository default branch is main; publish-next.yml exists only on next. GitHub's Actions UI only offers manual dispatch for a workflow defined on the default branch, so this trigger and its release_tag input were structurally inoperable — dead, misleading control surface. The workflow now triggers only on push of an approved prerelease tag (v*-beta.*, v*-rc.*, v*-next.*), with the tag derived solely from github.ref_name. Retries go through GitHub's rerun-failed-jobs control instead.
• B — split into three jobs. validate (contents: read, no environment) builds, tests, and packs the single tarball that can ever be published, records its SHA-256/identity/provenance metadata in a receipt, and uploads it as one artifact. publish (contents: read + id-token: write, environment: npm-next) has no checkout, no npm ci, no tests, no build, no repository scripts, and no dependency cache — it downloads and independently re-verifies that exact artifact, then npm publish is its last step with nothing after it. Environment approval sitting on publish (after validate passes) means a human approves a build already proven sound, not one they're approving in order to find out about. post_publish (contents: write, no id-token, no npm ci/build) restores publish's pre-publish dist-tags snapshot and consumes it to verify latest was preserved, runs the clean-install smoke test, and creates/edits the GitHub prerelease; it's idempotent and holds no publish credential, so a failure there can be rerun without any path back into publish.
• C — every action pinned to a full 40-character commit SHA with a version comment (actions/checkout, actions/setup-node, actions/upload-artifact, actions/download-artifact), resolved from the authoritative actions/* repos. ci.yml/release.yml untouched.
• D — recovery. npm versions are immutable, so nothing after a successful publish can be "fixed" by publishing again. publish ends at the publish command; post_publish create-or-edits the release, so reruns after a partial failure never touch publish and never republish.

Correction from lead review: the qualification gate was only half-deterministic

My first pass made qualify:validate hard-fail when present and notice when absent, and argued that was already deterministic. The lead correctly pointed out this covers only one direction: if the script is ever removed after #681 lands it — a bad refactor, a lost merge, a dependency bump rewriting package.json — presence-only detection silently falls back to the notice path and publishes anyway. That's the exact "permanently optional gate" the requirement forbids.

Fixed with a second, independent signal in new .github/scripts/check-qualification-gate.mjs: compares docs/qualification/ (the qualification contract, landing with #681 in the same merge as the script) against whether package.json still defines qualify:validate (the contract's validator). Script present → run for real. Script absent, contract present → hard fail naming exactly what's wrong. Script absent, contract absent → today's notice. Both fail-closed directions are unit-tested directly against the script; the lead independently ran all three cases against the script before accepting the fix.

Human setup checklist (unchanged, still not done)

1. Create the npm-next GitHub environment with required reviewers — it does not exist today.
2. Configure npm Trusted Publishing for @lubab/madar against this repository, publish-next.yml, and the npm-next environment.
3. Add tag protection for v* — there are currently no tag-targeting rulesets.

CI on the final commit

Six-job matrix (ubuntu/macos/windows × Node 20/22) is green on a7140d4f493827a7a92ceb2f5c688fcdd12467af: https://github.com/mohanagy/madar/actions/runs/31627193741.

Validation run locally

Typecheck, build, release:verify, registry:validate, verify:pack-parity, and release-pipeline.test.ts (48/48) all pass. test:run gave two different results across two attempts on this shared machine: attempt 1 had 0 assertion failures (8 files hit the known #654 fork-worker-start symptom and were counted passed by the same run's own tally, with no test.retry configured and no manual rerun by me — worth recording against #654 that this machine can silently absorb fork-worker failures within a single run by default); attempt 2, run while an unrelated vitest process with ~15 forked workers was confirmed active on this same machine, had 8 real assertion/timeout failures across files unrelated to this diff (2 of which I confirmed separately are contention/pre-existing, not regressions). Given that confirmed contention, I'm treating the isolated six-job CI matrix above as authoritative rather than either local run. test:coverage had 3 failures: 2 in compare-native-agent.test.ts were coverage-instrumentation timing flakiness (pass cleanly in isolation without coverage), and 1 in stdio-slice-surface.test.ts reproduces on the unmodified base commit 4f82365a — pre-existing, unrelated to the release pipeline, out of this PR's scope. Full detail is in PR #688's body.

Beta readiness verdict is unchanged from #688's original post: pipeline is ready for review and, with CI now green on the final commit, ready to merge into next pending the human setup checklist above; the beta itself remains not ready to publish — Phase 0 beta readiness is unmet and publication during the partial graph-integrity migration (#656 → #657 → #658 → #659) is not permitted. Refs #654, which remains open.

[mohanagy]

Infrastructure landed and human controls configured — this issue stays open

PR #688 is merged into next as 2e8a3737956fb6b15a18d682c04dd6a2a5a2e470. The six-job matrix is green on that commit. main is unchanged at 3371ada8.

Nothing was published. No package version, no Git tag, no GitHub release, no dist-tag change. npm latest remains 0.32.1 and no next dist-tag exists.

Human controls now configured and verified

npm-next GitHub environment (id 19795477925)

• Required reviewer: mohanagy; prevent_self_review: false, deliberately — with a single approving maintainer, preventing self-review would deadlock the first prerelease.
• can_admins_bypass set to false. It defaults to true, which would have let an admin skip the approval gate entirely and hollow out the human-approval requirement this issue specifies.
• Deployment restricted to three type: tag policies — v*-beta.*, v*-rc.*, v*-next.* — with no branch policies.
• Zero environment secrets, zero variables.

Tag ruleset protect-madar-prerelease-tags (id 20781196)

• target: tag, enforcement: active, restricting creation, update, and deletion.
• Includes exactly the three approved prerelease patterns; stable v* tags deliberately unaffected.
• Bypass: RepositoryRole:5:always. A bypass is required here — the repository's existing branch rulesets carry empty bypass_actors, which is exactly why the next ruleset had to be temporarily cleared during branch synchronization. Without it, the maintainer could not create the first prerelease tag.

npm Trusted Publishing

{ "id": "52c448dd-10c9-4d31-b701-98f9a67d2957",
  "type": "github", "file": "publish-next.yml",
  "repository": "mohanagy/madar", "environment": "npm-next",
  "permissions": ["createPackage"] }

Bound to the workflow filename and the protected environment, with createPackage only — no staged-publish permission. No npm token exists or is stored.

A constraint discovered while configuring this — it affects #676

npm permits exactly one trusted publisher per package. Attempting to add the prerelease binding alongside the existing one returned:

409 Conflict — trusted publisher config already exists for the package. Please delete and re-create.

The package previously had a publisher bound to release.yml with no environment, so it was gated by nothing. That binding was latent rather than live — release.yml holds no id-token: write and no workflow on next runs npm publish — but anyone adding id-token: write to it would have gained unattended publish rights with no approval. It was revoked (9d180f87-4bc6-4119-b75f-08b12dec399f) and replaced with the environment-protected binding above, on explicit maintainer authorization.

Consequence for #676: stable latest publication cannot simply add a second binding. Because only one publisher may exist per package, stable-versus-prerelease coexistence has to be solved deliberately — and any stable binding should have its own protected environment rather than inheriting the environment-less shape just removed.

Why this issue remains open

Ten of the thirteen acceptance criteria are implemented and covered by tests. Three describe runtime outcomes of an actual publication, which cannot be evidenced without publishing:

• clean install of the exact version reports that version;
• clean install of @next reports that version;
• the GitHub release is created with prerelease: true.

The code paths exist in post_publish and are structurally tested, but structural tests are not the same as observed behavior — and this issue's own standard is evidence, not intent. Two further criteria (fail-closed validation on the exact tagged commit, and provenance attached via Trusted Publishing) are configured and unit-tested but likewise unproven end to end.

Those criteria become satisfiable at the first real prerelease, which remains prohibited: publication must not occur during the partial graph-integrity migration #656 → #657 → #658 → #659. Publishing after only #657 or #658 would ship artifact, integrity, and answerability behavior in a deliberately incomplete state.

This issue therefore stays open, tracking the first v0.33.0-beta.1 publication as the remaining evidence.

Related tracking issue: #654 remains open.

[mohanagy]

Maintainer decision — keep open

Classification: implementation complete, activation not established.

The protected prerelease workflow exists, but no beta publication has exercised the channel end-to-end.

Evidence recorded from the read-only reconciliation at origin/next = 7d65ea1a:

• PR chore(release): add protected npm next prerelease channel #688 (2e8a3737) is an ancestor of origin/next and delivered .github/workflows/publish-next.yml (685 lines), classify-release-tag.mjs, verify-next-release-state.mjs, assert-clean-vitest-log.mjs, check-qualification-gate.mjs, and 940 lines of release-pipeline.test.ts.
• Present and verified in the merged workflow: OIDC Trusted Publishing (id-token: write), protected environment, provenance, ancestor-of-next proof, already-published rejection (assertVersionIsUnpublished), latest captured and verified unchanged (assertPostPublishState), clean-install resolution check, prerelease: true, tag-push-only triggers, and stable-vs-prerelease tag classification in release.yml. CHANGELOG/version matching lives in verify-release-hygiene.mjs.
• Not established: npm view @lubab/madar dist-tags returns {"latest":"0.32.1"} only. There is no next dist-tag, so no publication has ever run the workflow.

Do not publish a beta. Do not work on #687 now. This issue is not a development dependency for #659.

[mohanagy]

Superseded by #735. The context-pack-first roadmap is no longer the active product architecture after the negative anchored-product checkpoint. Relevant reusable ideas may be reintroduced only through #736 or a later evidence-backed issue. This closure does not imply that unimplemented acceptance criteria were completed.