ci: auto-stage npm version bumps (#13)

Author: ben

AGENTS.md

@@ -50,5 +50,5 @@
 - Keep `portfolio-inventory.json` byte-canonical and consistent with the public package identity, version, repository, direct `@hraness/*` dependency edges, and Hraness-owned dependencies pinned by exact immutable GitHub specifiers.
 - Pair concrete behavior tests with property tests for parsing, resolution, ordering, path confinement, and round-trip laws.
 - Run `bun test src/benchmark.test.ts src/evaluation.test.ts src/evaluation-kb.test.ts src/search.test.ts src/sdk.test.ts` when changing rank fusion, retrieval defaults, frozen-corpus execution, or built-in evaluation adapters. The six-case synthetic rank-fusion fixture is a deterministic regression, not a retrieval-quality or performance benchmark. Keep real-corpus manifests versioned, judgments independent of rankings, raw lane evidence intact, and performance claims tied to named hardware and measured runs. Run `bun run check` before handing off a change; it must leave committed `dist/` and `bun.lock` unchanged.
-- Follow `docs/publishing.md` for the interactive npm bootstrap and later stage-only trusted publishing. A `package.json` push to `main` may continue only when the exact prior and current manifests prove a strictly increasing stable package version; an unchanged version must stop successfully before verification or OIDC, and `workflow_dispatch` remains the current-`main` recovery path. Keep source checkout, install, build, test, pack, and artifact upload in a read-only job; only its minimal dependent staging job may request OIDC, and that job must use the protected `npm-stage` environment, require reviewer `0thernet` while allowing self-review, and rebind the exact three-file artifact and current `main` before the canonical-registry stage-only mutation. Bind npm's trusted publisher to that exact environment. Disallow traditional publishing tokens, inspect the staged tarball, and approve it with 2FA. Preserve `contentPolicy.class=dual-use` and the root `DISCLOSURE` in every published version.
+- Follow `docs/publishing.md` for the interactive npm bootstrap and later stage-only trusted publishing. A `package.json` push to `main` may continue only when the exact prior and current manifests prove a strictly increasing stable package version; an unchanged version must stop successfully before verification or OIDC, and `workflow_dispatch` remains the current-`main` recovery path. Keep source checkout, install, build, test, pack, and artifact upload in a read-only job; only its minimal dependent staging job may request OIDC, and that job must use the exact `npm-stage` environment, restrict deployments to `main` without required deployment reviewers, and rebind the exact three-file artifact and current `main` before the canonical-registry stage-only mutation. Bind npm's trusted publisher to that exact environment. Disallow traditional publishing tokens, inspect the staged tarball, and approve its promotion with human 2FA. Preserve `contentPolicy.class=dual-use` and the root `DISCLOSURE` in every published version.
 - Treat a `v*` tag as a release request, not a completed release. Publish the exact npm version first. Before tagging, confirm repository-level immutable releases are enabled; use a strictly increasing stable package version, keep the tag equal to `v<package.json version>` on `main`, and let the read-only verification job compare the source and registry packages by exact extracted path, type, mode, size, and regular-file hashes before its write-scoped publisher creates the Release. Verify each transport's npm and registry integrity independently because compressed tarball bytes may vary across operating systems. Recover a failed post-tag Release only through the explicit current-`main` workflow dispatch; bind the current workflow helpers to reviewed Git blobs and invoke them by absolute path against the tagged working tree after its explicit check/build, with tag-owned Bun config and environment loading disabled. Keep `npm pack --ignore-scripts` so recovery never depends on or reruns a historical `prepack`. Never move the tag or republish npm. Do not create the next tag until that workflow and Release are verified because GitHub concurrency is not a durable queue. After tagging, verify the matching non-draft immutable Release is Latest.

docs/publishing.md

@@ -77,10 +77,10 @@ in the npm package settings:
 - allowed action: `npm stage publish` only
 - environment: `npm-stage`
 
-Create the protected `npm-stage` GitHub environment before enabling later
-publishing. Require reviewer `0thernet`, allow that maintainer to approve their
-own deployment with `prevent_self_review: false`, and restrict deployments to
-`main`. The npm trusted publisher must name that exact environment. Then
+Create the `npm-stage` GitHub environment before enabling later publishing.
+Restrict deployments to `main` and configure no required deployment reviewers,
+so a verified version bump reaches npm staging without a second GitHub
+approval. The npm trusted publisher must name that exact environment. Then
 require publishing two-factor authentication and disallow traditional tokens.
 Do not add an npm publishing token to GitHub. Preserve
 `contentPolicy.class=dual-use` and the root `DISCLOSURE` in every package.
@@ -96,9 +96,9 @@ Do not add an npm publishing token to GitHub. Preserve
    `npm-pack.json`, and `npm-package.sha256`, bound to the source commit,
    version, complete inventory, size, integrity, dual-use declaration, and
    disclosure.
-3. Approve the protected `npm-stage` environment as a maintainer. The minimal
-   OIDC job then revalidates the artifact and current `main` before it stages
-   the package.
+3. The minimal OIDC job starts automatically after verification. Its exact
+   `npm-stage` environment allows only `main`, and the job revalidates the
+   artifact and current branch head before it stages the package.
 4. Inspect and approve the staged package through npm with two-factor
    authentication.
 5. Verify the public registry package in a clean consumer.
@@ -108,15 +108,16 @@ Do not add an npm publishing token to GitHub. Preserve
 
 If the automatic run is missing or fails before npm staging completes,
 dispatch **Stage npm package** from current `main`. Manual recovery runs the
-same verification and protected staging jobs. The workflow rejects a tag,
-another branch, or a commit behind the current default-branch head.
+same verification and main-branch-restricted staging jobs. The workflow rejects
+a tag, another branch, or a commit behind the current default-branch head.
 
 The verification job checks out source, installs dependencies without
 lifecycle scripts, runs the complete gate, creates the three-file artifact,
 and smokes the exact tarball. Its dependent staging job is the only job with
-OIDC authority, and the protected `npm-stage` environment requires maintainer
-approval before that job starts. It checks out no source and runs no repository
-code. It rebinds identity, filename, inventory, count, modes, sizes, SHA-1,
+OIDC authority. The exact `npm-stage` environment restricts deployments to
+`main` and has no required reviewers, so the job starts automatically after
+verification. It checks out no source and runs no repository code. It rebinds
+identity, filename, inventory, count, modes, sizes, SHA-1,
 SHA-512, and the independent SHA-256 manifest before mutation. Immediately
 before staging,
 it fetches current `main` into a new bare Git directory, then rehashes all

scripts/check-workflow-yaml.test.ts

@@ -53,7 +53,7 @@ jobs:
     )).toThrow("must recheck current default-branch HEAD");
   });
 
-  test("keeps npm staging version-selected, protected, tokenless, artifact-bound, and stage-only", async () => {
+  test("keeps npm staging version-selected, environment-bound, tokenless, artifact-bound, and stage-only", async () => {
     const path = resolve(import.meta.dir, "../.github/workflows/npm-stage.yml");
     const source = await readFile(path, "utf8");
 
@@ -101,13 +101,13 @@ jobs:
     expect(stage).not.toContain("./scripts/");
   });
 
-  test("requires the protected environment and fail-closed version selector", async () => {
+  test("requires the exact environment and fail-closed version selector", async () => {
     const path = resolve(import.meta.dir, "../.github/workflows/npm-stage.yml");
     const source = await readFile(path, "utf8");
     expect(() => validateNpmStageWorkflow(
       source.replace("environment: npm-stage", "environment: unprotected"),
       "npm-stage.yml",
-    )).toThrow("protected npm-stage environment");
+    )).toThrow("exact npm-stage environment");
     expect(() => validateNpmStageWorkflow(
       source.replace(
         'git show "$BEFORE_SHA:package.json"',

scripts/check-workflow-yaml.ts

@@ -85,7 +85,7 @@ export function validateNpmStageWorkflow(source: string, label: string): void {
     throw new Error(`${label} staging must hold only id-token: write`);
   }
   if (stage.environment !== "npm-stage") {
-    throw new Error(`${label} staging must use the protected npm-stage environment`);
+    throw new Error(`${label} staging must use the exact npm-stage environment`);
   }
   if (!Array.isArray(select.steps)) {
     throw new Error(`${label} select steps must be a sequence`);

scripts/npm-release-workflow.test.ts

@@ -315,23 +315,25 @@ describe("npm release workflows", () => {
       "Do not reuse the\ninteractive path for a later release",
       "[Stage a later version](#stage-a-later-version)",
       "version is unchanged",
-      "protected `npm-stage` environment",
-      "reviewer `0thernet`",
-      "`prevent_self_review: false`",
+      "exact `npm-stage` environment",
+      "configure no required deployment reviewers",
+      "allows only `main`",
       "rebinds the release helpers to their reviewed Git blobs",
       "invokes those files by absolute path",
       "`npm pack --ignore-scripts`",
       npmRegistry,
     ] as const) expect(guide).toContain(required);
     expect(guide).toMatch(/the only job with\s+OIDC authority/u);
-    expect(guide).toMatch(/requires maintainer\s+approval/u);
+    expect(guide).toMatch(/has no required reviewers, so the job starts automatically/u);
+    expect(guide).toMatch(/approve the staged package through npm with two-factor\s+authentication/u);
     expect(guide).toMatch(/checks out no source and runs no\s+repository\s+code/u);
     expect(guide).toMatch(/exactly the tarball,\s+`npm-pack\.json`, and `npm-package\.sha256`/u);
     expect(guide).toMatch(/new bare\s+Git directory/u);
     expect(guide).toMatch(/do not import a\s+script from the tagged tree/u);
     expect(agents).toContain("only its minimal dependent staging job may request OIDC");
-    expect(agents).toContain("protected `npm-stage` environment");
-    expect(agents).toContain("require reviewer `0thernet` while allowing self-review");
+    expect(agents).toContain("use the exact `npm-stage` environment");
+    expect(agents).toContain("restrict deployments to `main` without required deployment reviewers");
+    expect(agents).toContain("approve its promotion with human 2FA");
     expect(agents).toContain("bind the current workflow helpers to reviewed Git blobs");
     expect(agents).toContain("recovery never depends on or reruns a historical `prepack`");
   });