@kungfu-tech/buildchain 0.0.0-bootstrap.0 → 2.0.13-alpha.10

package/README.md

@@ -0,0 +1,262 @@
+# Kungfu Buildchain
+
+Kungfu Buildchain is the v2 source of truth for Kungfu reusable GitHub
+workflows, the minimal Buildchain-native GitHub Actions surface, and release-line
+automation.
+
+The repository does more than collect workflow files. Its main job is to make a
+Kungfu release auditable and repeatable: a protected branch merge should produce
+the right version commit, exact release tag, floating channel tag, and next
+alpha line without a maintainer hand-moving refs or repairing package metadata
+after the fact.
+
+## Why This Exists
+
+Kungfu release automation has to solve a few problems at the same time:
+
+- consumers need stable refs such as `v2`, `v2.0`, and `v2.0-alpha`;
+- maintainers need exact immutable refs such as `v2.0.2` and
+  `v2.0.3-alpha.0` for audit and rollback;
+- package manifests must record the same version that the release tag
+  advertises;
+- alpha and release promotion must follow reviewed PRs, not local scripts or
+  manually edited tags;
+- the release toolchain itself must be released by the same governance model
+  that it applies to product repositories.
+
+The older ABV model solved this by treating a GitHub release PR as the release
+intent. Buildchain v2 keeps that semantic contract, but implements it inside a
+modern monorepo with Node 24 actions, pnpm, tsup bundles, committed `dist`
+outputs, reusable workflow tests, package-manager adapters, and a TOML lifecycle
+protocol for non-Node projects.
+
+## Mental Model
+
+Buildchain release automation is branch-driven:
+
+| Merge path | Meaning | Exact tag | Floating tags and branches |
+| --- | --- | --- | --- |
+| `dev/vX/vX.Y -> alpha/vX/vX.Y` | publish the next testable alpha for a minor line | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y` |
+| `alpha/vX/vX.Y -> release/vX/vX.Y` | publish production for that minor line | `vX.Y.Z` | `vX.Y`, usually `vX`, `release/vX/vX.Y` |
+| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0` | `v(X+1)`, `v(X+1).0`, `release/v(X+1)/v(X+1).0` |
+
+After a production release, Buildchain prepares the next alpha source commit for
+the same minor line and moves `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and
+`vX.Y-alpha` to that next prerelease state. This is why a release can leave the
+production channel at `v2.0.2` while the test channel is already at
+`v2.0.3-alpha.0`.
+
+Kungfu treats minor lines as long-running product trains. `v2.0`, `v2.1`, and
+future minor refs can each receive many patch releases such as `v2.0.1234`.
+`v2` points at the selected stable major line, while `v2.0` points at the
+latest production patch for that minor line.
+
+`publish-gate/major` replaces the old ABV `main` channel. It is deliberately
+not named `main` because it is not the active development trunk. Maintainers use
+the same PR flow as other channel promotions: merging
+`release/v2/v2.0 -> publish-gate/major` means "publish the next major line from
+this production state." The promotion then creates the next major production
+version, for example `v3.0.0`, and prepares `dev/v3/v3.0` plus
+`alpha/v3/v3.0` at `v3.0.1-alpha.0`. The older `major-gate` branch name is only
+a compatibility alias during migration.
+
+Exact tags are always v-prefixed. Use `v2.0.0` and `v2.0.1-alpha.0`; bare tags
+such as `1.0.0` are not maintained as Buildchain release entrypoints.
+
+## Repository Layout
+
+```text
+.github/workflows/        Repository checks, reusable workflows, and release promotion
+actions/                  GitHub Actions implementations, grouped by action
+fixtures/                 Safe fixture repositories or fixture descriptors
+packages/                 Shared libraries, added only when justified
+tests/                    Inventory and contract data used by checks
+docs/                     Governance, migration, architecture, and rollback notes
+scripts/                  Local verification scripts
+```
+
+## Buildchain v2 Contract
+
+Buildchain v2 ships these active surfaces:
+
+- repository workflows under `.github/workflows`;
+- the public npm package `@kungfu-tech/buildchain` and `buildchain` CLI for
+  initializing and validating new repositories;
+- the active reusable build workflow `.github/workflows/.build.yml`;
+- exactly three GitHub Actions under `actions/<name>`:
+  `validate-config`, `run-lifecycle`, and `promote-buildchain-ref`;
+- action runtime on Node 24;
+- workspace package management with pnpm;
+- action bundling through tsup;
+- committed `dist/index.js` bundles for direct GitHub Actions consumption;
+- package-manager adapters for pnpm, npm, and yarn version-state updates;
+- `buildchain.toml` lifecycle configuration for custom version files and
+  verification commands;
+- `project.type = "web-surface"` configuration for site and app repositories
+  that need preview/staging/production deployment manifests and dry-run deploy
+  plans without package-release version semantics;
+- opt-in anchored/manual version strategy for packages whose version is pinned
+  to an explicit upstream release instead of derived from the Buildchain tag;
+- `actions/validate-config` migration preflight for TOML version-state and
+  lifecycle declarations without running heavyweight builds;
+- `.github/workflows/.build.yml` as the reusable build surface for
+  tri-platform runner presets, custom runner matrices, caller-provided lifecycle
+  commands, trusted event gating, artifact name templates, expected artifact
+  checks, deterministic artifact manifests, publish-gate source locks, resolved
+  release manifests, and aggregate build summaries;
+- `actions/run-lifecycle` for callers that need the same lifecycle/manifest
+  contract inside their own workflows;
+- governance-closed self-promotion through `Buildchain Ref Promotion`.
+
+Stable consumers should reference actions as:
+
+```yaml
+uses: kungfu-systems/buildchain/actions/<name>@v2
+```
+
+Documented reusable workflows should be referenced as:
+
+```yaml
+uses: kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v2
+```
+
+Repositories can also bootstrap local integration through the CLI:
+
+```bash
+npx @kungfu-tech/buildchain init --type package
+npx @kungfu-tech/buildchain validate --require-version-state
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.0
+npx @kungfu-tech/buildchain npm dry-run --json
+```
+
+Standalone `workflows` and `action-*` repositories are historical rollback
+anchors. Buildchain no longer ships migrated copies of legacy action
+repositories.
+
+Some hidden reusable workflow files from the old `workflows` repository still
+exist in this repository so they can be linted, audited, and made fail-closed
+while consumers migrate. They are not Buildchain-native release or publish
+surfaces unless this README or a dedicated document explicitly names them.
+Modern package, artifact, and publish integrations should use `.build.yml`,
+`buildchain.toml`, lifecycle commands, and publish transaction evidence instead
+of retired legacy action paths.
+
+## Release Governance
+
+Buildchain promotes its own release refs through
+`.github/workflows/buildchain-ref-promotion.yml` and
+`actions/promote-buildchain-ref`.
+
+The important constraints are:
+
+- non-dry-run promotion is not available from manual dispatch;
+- promotion must be backed by a protected same-repository PR channel path;
+- protected channel details must be readable and must enforce protection for
+  administrators;
+- alpha promotion must come from `dev/vX/vX.Y -> alpha/vX/vX.Y`;
+- release promotion must come from `alpha/vX/vX.Y -> release/vX/vX.Y`;
+- major promotion must come from `release/vX/vX.Y -> publish-gate/major`;
+- release promotion must match an existing same-patch alpha tag tree;
+- generated version-state commits must pass the configured verification command
+  before refs move;
+- `BUILDCHAIN_PROMOTION_TOKEN` is the release authority used to move protected
+  refs when repository policy requires it.
+
+Buildchain's top-level `Release - New Version` workflow is intentionally a
+no-op for this repository. Buildchain itself is promoted only by
+`Buildchain Ref Promotion` after `Verify` succeeds. The legacy hidden
+`.release-new-version.yml` file is not the modern publish surface; it remains a
+migration boundary for old consumers and must not be used for new Buildchain v2
+integrations.
+
+Buildchain's npm package is published by the same promotion transaction that
+creates exact v-prefixed release tags. Alpha releases such as
+`v2.0.13-alpha.0` publish to npm with dist-tag `alpha`; stable releases such as
+`v2.0.13` publish with dist-tag `latest`. Floating refs like `v2`, `v2.0`, and
+`v2.0-alpha` never publish npm packages. The old tag-push npm workflow is
+dry-run only; real npm publish happens before public release refs move, using
+the evidence contract in `lifecycle.publish`.
+
+For release-line planning, use the CLI dry-run:
+
+```bash
+buildchain release --dry-run --target-ref release/v2/v2.0 --sha <verified-sha>
+```
+
+This prints the branch/tag/version-state/governance plan that a channel merge
+would trigger. It is intentionally separate from `buildchain npm dry-run`, which
+only checks package publish shape.
+
+## Read Next
+
+- [Release governance](docs/release-governance.md) explains the design problem,
+  old ABV compatibility, hard constraints, and operational guarantees.
+- [Release flow diagrams](docs/release-flow.md) gives the branch/tag state
+  machine and Mermaid diagrams.
+- [Migration inventory](docs/migration-inventory.md) lists migrated and retired
+  action repositories.
+- [Ownership rules](docs/ownership.md) defines source-of-truth and rollback
+  boundaries.
+- [promote-buildchain-ref](actions/promote-buildchain-ref/README.md) documents
+  the internal promotion action.
+- [Lifecycle protocol](docs/lifecycle-protocol.md) documents `buildchain.toml`
+  for custom version-state files and lifecycle commands.
+- [Reusable build surface](docs/reusable-build-surface.md) documents the build
+  workflow, local runner matrix, artifact contract, and libnode-shaped fixture.
+- [Web-surface deployments](docs/web-surface-deployments.md) documents the
+  preview/staging/production channel ontology, deployment manifest, adapter
+  contract, and dry-run cleanup/deploy plans.
+- [Buildchain CLI and npm package](docs/cli.md) documents the npm package,
+  command-line entrypoint, repository bootstrap flow, and release-only publish
+  gate.
+
+## Local Verification
+
+```bash
+corepack enable pnpm
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+`pnpm run check` validates inventory data, lints all root workflows including
+hidden reusable workflows, and rebuilds every action bundle.
+
+## Lifecycle Configuration
+
+Projects can add `buildchain.toml` to declare release version state and
+lifecycle commands. Buildchain v2 supports TOML only. The promotion action uses
+configured version files to create source version commits, then runs
+`lifecycle.verify` before moving release refs. Repositories that publish
+external artifacts can also declare `lifecycle.publish`; with publish
+transactions enabled, Buildchain requires machine-readable evidence before exact
+release tags and floating channel refs move.
+
+Web-surface projects can also declare `project.type = "web-surface"` with
+preview, staging, and production channels. Those projects get deployment
+manifests and dry-run deploy/cleanup plans, but they are not forced into package
+version lines or anchored release semantics.
+
+## Safety Defaults
+
+- Lab workflows are manual by default.
+- Publishing is disabled unless explicitly enabled by a production release
+  workflow. Reusable builds expose `publish-channel`, `publish-allowed`, and
+  `publish-reason` so callers can gate publish jobs on a reviewed channel ref
+  instead of inferring publish eligibility from ad hoc branch checks.
+- Publish gate branches are resolved to a source SHA before checkout. Builds,
+  verification, artifact manifests, and summaries use that locked SHA; publish
+  jobs must re-check the branch tip before external side effects.
+- Publish transactions are keyed by repository, version, source SHA, and target
+  ref rather than run id. Reruns may resume missing artifacts, accept matching
+  existing artifacts, and fail closed on conflicting material until an explicit
+  repair override is used.
+- Fork pull requests must not reach secrets or self-hosted runners.
+- Candidate refs are expected to come from `kungfu-systems/*`.
+- Self-hosted runner validation is available only through the manual
+  `Self-hosted Runner Smoke` workflow.
+
+## Read Next
+
+- [Lifecycle protocol](docs/lifecycle-protocol.md)
+- [Publish transaction](docs/publish-transaction.md)
+- [Reusable build surface](docs/reusable-build-surface.md)

package/bin/buildchain.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { initBuildchainRepo } from "../scripts/init-repo.mjs";
+import { npmPublishDryRun } from "../scripts/npm-publish-dry-run.mjs";
+import { runLifecycle } from "../scripts/run-lifecycle-core.mjs";
+import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
+import {
+  explainReleaseLineDryRun,
+  formatReleaseLineDryRun,
+} from "../packages/core/release-line-dry-run.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function usage() {
+  return `Usage:
+  buildchain --help
+  buildchain version
+  buildchain init [--cwd <dir>] [--type package|native|web-surface|anchored-package] [--force]
+                  [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
+                  [--artifact-name <template>]
+  buildchain validate [--cwd <dir>] [--require-version-state]
+                      [--require-lifecycle-stages <comma-list>]
+  buildchain lifecycle run <stage> [--cwd <dir>] [--required]
+                             [--artifact-name <name>] [--artifact-path <path>]...
+  buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]
+                         [--dist-tag <tag>] [--skip-npm-publish-dry-run] [--json]
+  buildchain release --dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                 [--tags <comma-list>] [--json]
+  buildchain release dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                      [--tags <comma-list>] [--json]
+  buildchain release <inspect|recover|finalize|abort> ...
+  buildchain web-surface ...
+  buildchain publish-source <lock|manifest|verify-lock> ...
+  buildchain build-contract ...
+
+Examples:
+  buildchain init --type package --package-manager pnpm
+  buildchain validate --require-version-state --require-lifecycle-stages build,verify
+  buildchain lifecycle run build --artifact-path dist --artifact-name "{repo}-{version}-{platform}"
+  buildchain npm dry-run --json
+  buildchain release --dry-run --target-ref alpha/v2/v2.0
+`;
+}
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return args[index + 1] || "";
+}
+
+function readBooleanFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+function readRepeatedFlag(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === `--${name}` && args[index + 1]) {
+      values.push(args[index + 1]);
+      index += 1;
+    }
+  }
+  return values;
+}
+
+function runScript(scriptName, args) {
+  const scriptPath = path.join(root, "scripts", scriptName);
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  process.exitCode = result.status ?? 1;
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function packageVersion() {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  return packageJson.version;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const [command, ...args] = argv;
+  if (!command || command === "-h" || command === "--help" || command === "help") {
+    process.stdout.write(usage());
+    return;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    process.stdout.write(`${packageVersion()}\n`);
+    return;
+  }
+
+  if (command === "init") {
+    const result = initBuildchainRepo({
+      cwd: readFlag(args, "cwd", process.cwd()),
+      type: readFlag(args, "type", "package"),
+      force: readBooleanFlag(args, "force"),
+      packageManager: readFlag(args, "package-manager", ""),
+      runnerPreset: readFlag(args, "runner-preset", "github-hosted"),
+      artifactName: readFlag(args, "artifact-name", "{repo}-{version}-{platform}"),
+    });
+    printJson(result);
+    return;
+  }
+
+  if (command === "validate") {
+    const lifecycleStages = readFlag(args, "require-lifecycle-stages", "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    printJson(validateBuildchainConfig(readFlag(args, "cwd", process.cwd()), {
+      requireVersionState: readBooleanFlag(args, "require-version-state"),
+      requireLifecycleStages: lifecycleStages,
+    }));
+    return;
+  }
+
+  if (command === "lifecycle") {
+    const [subcommand, stageName = "", ...lifecycleArgs] = args;
+    if (subcommand !== "run" || !stageName) {
+      throw new Error("usage: buildchain lifecycle run <stage>");
+    }
+    const artifactPaths = readRepeatedFlag(lifecycleArgs, "artifact-path");
+    const manifest = runLifecycle({
+      cwd: readFlag(lifecycleArgs, "cwd", process.cwd()),
+      stageName,
+      required: readBooleanFlag(lifecycleArgs, "required"),
+      artifactName: readFlag(lifecycleArgs, "artifact-name", "buildchain-artifact"),
+      artifactPaths,
+      expectedArtifactsJson: readFlag(lifecycleArgs, "expected-artifacts-json", ""),
+      workspace: process.cwd(),
+    });
+    printJson(manifest);
+    return;
+  }
+
+  if (command === "npm") {
+    const [subcommand = "", ...npmArgs] = args;
+    if (subcommand !== "dry-run") {
+      throw new Error("usage: buildchain npm dry-run");
+    }
+    const result = npmPublishDryRun({
+      cwd: readFlag(npmArgs, "cwd", process.cwd()),
+      expectedTag: readFlag(npmArgs, "expected-tag", ""),
+      registry: readFlag(npmArgs, "registry", "https://registry.npmjs.org/"),
+      distTag: readFlag(npmArgs, "dist-tag", ""),
+      skipNpmPublishDryRun: readBooleanFlag(npmArgs, "skip-npm-publish-dry-run"),
+    });
+    if (readBooleanFlag(npmArgs, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`npm publish dry-run ok: ${result.package.name}@${result.package.version} -> ${result.distTag}\n`);
+      process.stdout.write(`pack entries: ${result.pack.entryCount}\n`);
+    }
+    return;
+  }
+
+  if (command === "release") {
+    const releaseArgs = args[0] === "dry-run" ? args.slice(1) : args;
+    if (args[0] === "dry-run" || readBooleanFlag(args, "dry-run")) {
+      const plan = explainReleaseLineDryRun({
+        cwd: readFlag(releaseArgs, "cwd", process.cwd()),
+        targetRef: readFlag(releaseArgs, "target-ref", ""),
+        sourceRef: readFlag(releaseArgs, "source-ref", ""),
+        sha: readFlag(releaseArgs, "sha", ""),
+        tags: readFlag(releaseArgs, "tags", ""),
+        publishTransaction: readBooleanFlag(releaseArgs, "publish-transaction"),
+        publishCommand: readFlag(releaseArgs, "publish-command", ""),
+      });
+      if (readBooleanFlag(releaseArgs, "json")) {
+        printJson(plan);
+      } else {
+        process.stdout.write(formatReleaseLineDryRun(plan));
+      }
+      return;
+    }
+    runScript("release-transaction.mjs", args);
+    return;
+  }
+
+  if (command === "web-surface") {
+    runScript("web-surface.mjs", args);
+    return;
+  }
+
+  if (command === "build-contract") {
+    runScript("resolve-build-contract.mjs", args);
+    return;
+  }
+
+  if (command === "publish-source") {
+    const [mode = "lock", ...publishArgs] = args;
+    if (mode === "lock" || mode === "manifest") {
+      runScript("resolve-publish-source.mjs", ["--mode", mode, ...publishArgs]);
+      return;
+    }
+    if (mode === "verify-lock") {
+      runScript("verify-publish-source-lock.mjs", publishArgs);
+      return;
+    }
+    throw new Error(`unsupported publish-source command: ${mode}`);
+  }
+
+  throw new Error(`unsupported buildchain command: ${command}`);
+}
+
+main().catch((error) => {
+  console.error(`buildchain: ${error.message}`);
+  process.exitCode = 1;
+});

package/docs/cli.md

@@ -0,0 +1,124 @@
+# Buildchain CLI and npm Package
+
+Buildchain is published as the public npm package
+`@kungfu-tech/buildchain`. The package contains the `buildchain` command,
+the shared core libraries, and the local scripts needed to initialize and
+validate repositories before they use the reusable GitHub workflow surface.
+
+The npm package is not the release authority. Release authority still comes
+from the protected Buildchain branch and tag state machine. npm publishing is a
+side effect of an exact release tag that has already been produced by that
+state machine.
+
+## Install and Run
+
+Use the published package directly:
+
+```bash
+npx @kungfu-tech/buildchain --help
+npx @kungfu-tech/buildchain init --type package
+npx @kungfu-tech/buildchain validate --require-version-state
+```
+
+Or install it in a repository:
+
+```bash
+pnpm add -D @kungfu-tech/buildchain
+pnpm exec buildchain validate
+```
+
+## Commands
+
+`buildchain init` writes a starter `buildchain.toml` and a reusable workflow
+caller at `.github/workflows/build.yml`.
+
+Supported presets:
+
+- `--type package` for Node package repositories with pnpm, npm, or yarn.
+- `--type native` for CMake-style native projects.
+- `--type web-surface` for preview/staging/production site or app deployments.
+- `--type anchored-package` for packages whose version is anchored to an
+  explicit upstream release manifest.
+
+`buildchain validate` parses `buildchain.toml`, checks configured version-state
+files, and can require named lifecycle stages:
+
+```bash
+buildchain validate \
+  --require-version-state \
+  --require-lifecycle-stages install,build,verify
+```
+
+`buildchain lifecycle run <stage>` executes a lifecycle stage and writes the
+same deterministic artifact manifest contract used by the reusable workflow:
+
+```bash
+buildchain lifecycle run build \
+  --artifact-path dist \
+  --artifact-name "{repo}-{version}-{platform}"
+```
+
+`buildchain release`, `buildchain web-surface`, `buildchain publish-source`,
+and `buildchain build-contract` route to the same scripts used by Buildchain's
+GitHub Actions workflows. This keeps local inspection and CI behavior on the
+same implementation path.
+
+`buildchain release --dry-run` explains the release-line state machine before a
+maintainer opens or merges a channel PR:
+
+```bash
+buildchain release --dry-run --target-ref alpha/v2/v2.0
+buildchain release --dry-run --target-ref release/v2/v2.0 --sha <verified-sha>
+buildchain release dry-run --target-ref publish-gate/major --source-ref release/v2/v2.0
+```
+
+This is a Buildchain-level dry-run, not an npm dry-run. It explains the legal
+source branch, exact release or alpha tags, floating tags, channel branches,
+version-state files, governance checks, and publish transaction behavior that
+would apply if the corresponding PR merge were promoted. It does not move
+branches, move tags, edit files, publish npm packages, or run lifecycle publish
+commands. Pass `--json` for a machine-readable plan.
+
+`buildchain npm dry-run` verifies the package shape before a release tag exists:
+
+```bash
+buildchain npm dry-run --json
+```
+
+The command validates `package.json`, infers the exact release tag
+`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and
+`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs
+`npm publish --dry-run --access public --tag <alpha|latest>` unless
+`--skip-npm-publish-dry-run` is passed. It never performs a real publish.
+
+## npm Publish Gate
+
+Buildchain's own npm package is published from
+`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish
+transaction that promotes release refs:
+
+- `v2.0.13-alpha.0` publishes to npm with dist-tag `alpha`.
+- `v2.0.13` publishes to npm with dist-tag `latest`.
+- moving refs such as `v2`, `v2.0`, and `v2.0-alpha` do not match the publish
+  workflow and do not publish.
+
+The promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.
+It runs on a GitHub-hosted runner with `id-token: write`, generates the
+version-state commit, runs `lifecycle.verify`, runs `lifecycle.publish`, writes
+Buildchain publish evidence, validates that evidence, and only then moves exact
+tags and floating refs.
+
+```bash
+node scripts/npm-publish-transaction.mjs
+```
+
+Before the first real release, configure npm Trusted Publishing for:
+
+- package: `@kungfu-tech/buildchain`
+- repository: `kungfu-systems/buildchain`
+- workflow: `.github/workflows/buildchain-ref-promotion.yml`
+
+No npm package is published by manual dispatch or ordinary branch builds.
+Manual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so
+maintainers can verify package contents and npm publish shape before opening or
+merging the release PR.