Use staged npm publishing for language releases

.github/workflows/release-language.yaml

@@ -37,8 +37,8 @@ jobs:
           registry-url: https://registry.npmjs.org
           package-manager-cache: false
 
-      - name: Install trusted publishing npm CLI
-        run: npm install --global npm@11.5.1
+      - name: Install staged publishing npm CLI
+        run: npm install --global npm@11.15.0
 
       - name: Install dependencies
         run: npm ci
@@ -71,6 +71,6 @@ jobs:
             echo "published=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Publish package
+      - name: Stage package for publishing
         if: steps.package.outputs.published != 'true'
-        run: npm publish --workspace @stack-sh/language --access public
+        run: npm stage publish --workspace @stack-sh/language --access public

README.md

@@ -20,6 +20,7 @@ The language is currently a proposal for Stack 1.0. No compatibility guarantee a
 - [Examples](./examples)
 - [Conformance suite](./conformance)
 - [`@stack-sh/language`](./packages/language)
+- [Language package release process](./RELEASING.md)
 
 ## Example
 

RELEASING.md

@@ -0,0 +1,36 @@
+# Releasing `@stack-sh/language`
+
+The package is public and is released from this public repository. Release artifacts must come from a merged `main` revision whose `conformance-data` and `language-package` checks have passed.
+
+## First release
+
+The npm package must exist before its trusted publisher can be configured. An authenticated maintainer with publish access to the `@stack-sh` scope performs the one-time bootstrap from a clean `main` checkout:
+
+```sh
+npm ci
+npm run test:language
+npm run typecheck:language
+npm run pack:check
+npm publish --workspace @stack-sh/language --access public
+```
+
+After `@stack-sh/language` exists on npm, configure its trusted publisher with these exact values:
+
+- Provider: GitHub Actions
+- Organization: `stack-sh`
+- Repository: `specification`
+- Workflow filename: `release-language.yaml`
+- Allowed action: `npm stage publish`
+
+Then create the `language-v0.1.0` GitHub Release from the same merged revision. The release workflow recognizes that the package version already exists and completes without staging it twice.
+
+## Subsequent releases
+
+1. Update the language package version in a pull request.
+2. Run the complete repository checks and merge the pull request.
+3. Create a GitHub Release whose tag is exactly `language-v<package version>` and targets the merged commit.
+4. Verify that the release workflow stages the package through npm trusted publishing.
+5. Inspect the staged package on npm, then approve it with two-factor authentication.
+6. Verify the public registry metadata, provenance, and a clean consumer import.
+
+The workflow rejects a tag that does not match the package version. It validates the package again on the tagged revision, uses no long-lived npm token, and leaves npm provenance enabled. A package does not become public until a maintainer explicitly approves the staged version with two-factor authentication.