@kungfu-tech/buildchain 2.0.16-alpha.0 → 2.0.16

package/actions/promote-buildchain-ref/README.md

@@ -0,0 +1,202 @@
+# promote-buildchain-ref
+
+Internal buildchain action for promoting verified buildchain release-line and
+compatibility refs from buildchain release channels:
+
+- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as
+  `v2.0.1-alpha.0`, writes that version into package version state, points the
+  alpha and dev channel branches at the version commit, then promotes
+  `v2.0-alpha`;
+- `release/v2/v2.0` creates or reuses the next exact release tag such as
+  `v2.0.0`, writes that version into package version state, points the release
+  channel branch and release tags at the release commit, then prepares a second
+  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and
+  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease
+  commit;
+- `publish-gate/major` accepts a reviewed PR from a production release line such
+  as `release/v2/v2.0`, writes the next major production version such as
+  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`
+  at that release commit, then prepares `v3.0.1-alpha.0` for
+  `alpha/v3/v3.0`, `dev/v3/v3.0`, and `v3.0-alpha`. The older `major-gate`
+  branch name is a compatibility alias only.
+
+The release branch name defines the minor line. For example,
+`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only
+when the next minor tag such as `v2.2` does not already exist.
+
+The action updates version state in `lerna.json`, root `package.json`, and
+workspace package manifests discovered from package manager metadata
+(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).
+Package manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded
+in logs.
+
+Repositories can also provide `buildchain.toml` to declare version-state files
+and `lifecycle.verify`. TOML-configured version files take precedence over
+package-manager discovery and can target JSON, TOML, or regex-based files. The
+version commit itself is written through the GitHub Git Data API so the ref
+graph is the durable source of truth. Repositories without any supported version
+state degrade to ref-only promotion only when strict version state is disabled.
+
+## Dry Run
+
+Use `dry-run: "true"` or the CLI `buildchain release --dry-run` before merging a
+channel PR when you need to understand what Buildchain would do. This dry-run is
+at the Buildchain release-line level. It explains:
+
+- the legal source branch for the target channel;
+- exact release or alpha tags that would be created or reused;
+- floating tags and channel branches that would move;
+- version-state files and verification lifecycle that would apply;
+- branch protection, PR lineage, and release-from-alpha checks;
+- publish transaction behavior when `lifecycle.publish` or
+  `publish-transaction` is enabled.
+
+It does not move refs, move tags, write package files, run publish commands, or
+publish npm packages. The GitHub action dry-run still calls GitHub APIs to
+resolve the current target SHA and concrete pending ref updates, but every
+write is reported as a dry-run update.
+
+Repositories whose package version is anchored to an explicitly selected
+upstream release can opt into manual next-anchor behavior:
+
+```toml
+[version]
+required = true
+strategy = "anchored"
+next = "manual"
+manifest = "libnode.release.json"
+```
+
+In this mode, the action validates the configured version files and anchor
+manifest through the repository's verify lifecycle, but it does not rewrite the
+package version to match the Buildchain release tag. After a production
+release, it sets `next-anchor-required=true` and does not auto-create the next
+alpha branch or tag. The repository must create the next upstream anchor line
+explicitly, then run the normal channel promotion flow for that line.
+
+When branch protection requires pull requests, generated version-state commits
+are also routed through pull requests. The action creates an internal
+`buildchain/version-state/...` branch and PR, then stops before moving tags. Once
+that PR is reviewed, checked, and merged, the next promotion run verifies that
+the merge only changed declared version-state files from the legal source
+parent, then moves exact and floating refs.
+
+## Publish Transactions
+
+Promotion can also own external publish side effects. Enable this only from a
+trusted channel workflow:
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+  with:
+    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+    sha: ${{ github.sha }}
+    target-ref: release/v2/v2.0
+    publish-transaction: "true"
+    publish-mode: publish-final-version
+    publish-auth: trusted-publishing
+    publish-required-artifacts-json: >-
+      [
+        {"kind":"npm","name":"@kungfu-tech/buildchain","ref":"2.0.0","digest":"sha256:..."}
+      ]
+```
+
+When enabled, the action creates or resumes a release transaction keyed by
+repository, version, source SHA, and target ref. It persists that transaction to
+a machine-managed branch under `buildchain/release-state/<version>`, with
+`state.json` and, once available, `evidence.json`. Fresh GitHub runners read
+that durable ref before running publish, so reruns do not depend on a previous
+runner's local `.buildchain` directory.
+
+The action runs `lifecycle.publish` from `buildchain.toml` or the explicit
+`publish-command` input, then validates publish evidence before exact tags and
+floating refs move. If durable state persistence fails, the action fails closed
+before publish or public ref finalization.
+
+`publish-mode` defaults to `publish-final-version`, the token-free path for
+normal npm Trusted Publishing. Same-version alpha-to-latest recovery must be
+declared as `publish-mode: promote-existing-version` and
+`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates
+release-state or moves any `npm dist-tag`. The Trusted Publishing mode is not
+allowed to perform `npm dist-tag add`.
+
+Buildchain itself uses this path for npm. Its `lifecycle.publish` runs
+`node scripts/npm-publish-transaction.mjs`, which publishes
+`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm
+artifact evidence into the transaction before release refs move. The separate
+`.github/workflows/npm-publish.yml` workflow is dry-run only.
+
+Publish lifecycle environment:
+
+```text
+BUILDCHAIN_VERSION
+BUILDCHAIN_CHANNEL
+BUILDCHAIN_SOURCE_SHA
+BUILDCHAIN_TARGET_REF
+BUILDCHAIN_RELEASE_STATE
+BUILDCHAIN_EVIDENCE_DIR
+BUILDCHAIN_RELEASE_SHA
+BUILDCHAIN_RELEASE_MATERIAL_SHA
+BUILDCHAIN_PUBLISH_TOOLING_SHA
+BUILDCHAIN_PUBLISH_EVIDENCE
+```
+
+The action outputs `transaction-id`, `transaction-state`,
+`transaction-exact-tag`, `transaction-release-sha`, `transaction-state-ref`,
+`transaction-state-sha`, `transaction-state-path`, `publish-evidence-path`, and
+`finalization-needed`. `transaction-state-ref` is the durable recovery location.
+`finalization-needed=true` means publish evidence is valid, but protected branch
+or ref finalization needs a later promotion run.
+
+Finalization recovery is anchored to the durable transaction, not to a single
+workflow run SHA. After a generated version-state PR is merged, the current
+channel head can be a merge commit that contains or corresponds to the recorded
+`release_material_sha`; it does not have to equal the original `source_sha` or
+the transaction `release_sha`. Reruns accept exact tags that already point at
+the transaction release/material SHA or the finalized channel head, and continue
+moving any missing floating tags or dev/alpha refs before marking the
+transaction `complete`.
+
+Normal reruns accept already-published artifacts only when evidence matches.
+Missing required artifacts can be published on the next run. Conflicting
+artifacts put the transaction into `repair_required`; `abandoned` and
+`failed_permanently` also fail closed unless `publish-transaction-override` is
+set for a controlled repair.
+
+In strict buildchain promotion, ref movement is also gated by the old ABV
+governance semantics:
+
+- the target channel branch protection details must be readable, must enforce
+  protection for administrators, and must require approving PR review plus the
+  strict `check` job from the `Verify` workflow;
+- alpha promotion must come from a merged same-repository PR
+  `dev/vN/vN.M -> alpha/vN/vN.M`;
+- release promotion must come from a merged same-repository PR
+  `alpha/vN/vN.M -> release/vN/vN.M`;
+- major promotion must come from a merged same-repository PR
+  `release/vN/vN.M -> publish-gate/major`;
+- release promotion must have an exact alpha tag for the same patch line, and
+  the release source tree must match that alpha tag tree, so release does not
+  introduce new code after alpha;
+- generated release and next-alpha version-state trees can be verified locally
+  with either the `verification-command` input or `buildchain.toml`
+  `lifecycle.verify` before any tags or channel refs move.
+
+The promotion workflow should use `BUILDCHAIN_PROMOTION_TOKEN` for non-dry-run
+promotion. The token is the buildchain equivalent of the old ABV runner release
+authority: protected branch review and check rules guard human channel merges,
+while this action independently rechecks PR lineage, alpha/release tree
+equivalence, and generated version-state verification before moving channel
+refs and tags.
+
+The tag names intentionally follow the old ABV release semantics:
+exact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating
+release tags are minor/major tags such as `v2.0` and `v2`, and floating alpha
+tags are minor-line tags such as `v2.0-alpha`. Bare tags such as `1.0.0` are not
+maintained as buildchain release entrypoints.
+
+Repository rulesets should protect exact tags, not every `v*` tag. A ruleset
+such as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha`,
+which Buildchain must update after exact tags and publish evidence are durable.
+Use an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and
+leave floating channel tags mutable for the promotion token.

package/actions/run-lifecycle/README.md

@@ -0,0 +1,41 @@
+# run-lifecycle
+
+Run a Buildchain lifecycle stage or an explicit command and write a deterministic
+artifact manifest.
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/run-lifecycle@v2
+  with:
+    stage: build
+    required: "true"
+    artifact-name: my-product-linux-x64-${{ github.sha }}
+    artifact-paths: |
+      dist
+      build/stage
+```
+
+When `command` is provided, it overrides `buildchain.toml` for that invocation.
+When `command` is empty, the action loads `buildchain.toml` and runs the named
+stage.
+
+The action writes both a full manifest and a compact summary. It also exposes
+the summary as outputs for reusable workflow callers:
+
+| Output | Meaning |
+| --- | --- |
+| `manifest-path` | Full manifest path |
+| `summary-path` | Compact summary path |
+| `artifact-name` | Resolved artifact name |
+| `artifact-file-count` | Number of manifest files |
+| `artifact-total-bytes` | Total manifest bytes |
+| `artifact-summary-json` | One-line JSON summary |
+| `expected-artifacts-ok` | `true` when expectations passed |
+
+`expected-artifacts-json` can require exact paths, file count bounds, and a
+minimum byte total:
+
+```yaml
+with:
+  expected-artifacts-json: >-
+    {"minFiles":2,"requiredPaths":["dist/app.tar.gz","dist/checksums.txt"]}
+```

package/actions/validate-config/README.md

@@ -0,0 +1,34 @@
+# validate-config
+
+Buildchain v2 action for validating `buildchain.toml` without running lifecycle
+commands.
+
+Use this action during repository migration when a heavyweight project needs to
+prove that its Buildchain version state and lifecycle declaration are ready, but
+the actual build should not run yet.
+
+## Usage
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/validate-config@v2
+  with:
+    require-version-state: "true"
+    require-lifecycle-stages: "install,build,verify"
+```
+
+The action checks:
+
+- `buildchain.toml` exists and uses schema `1`;
+- configured version-state files exist and expose a string version;
+- anchored/manual version strategy declarations and JSON/TOML anchor manifests
+  are structurally valid when configured;
+- web-surface project, channel, deploy adapter, retention, and staging security
+  declarations are structurally valid when configured;
+- required lifecycle stages are declared and structurally valid.
+
+It does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,
+or any other lifecycle command.
+
+Outputs include `project-type`, `project-name`, `project-site`, `channels`, and
+`deploy-adapters-json`, so callers can route site workflows without reparsing
+TOML in every repository.

package/docs/MAP.md

@@ -0,0 +1,64 @@
+# Documentation Map
+
+Start here. Find the question you have; follow it to the document that answers
+it. This map is meant to be readable by both a person skimming for the right doc
+and an agent grounding a specific claim.
+
+Each row carries a **plane** - *why* (intent / rationale), *verify* (trust the
+running artifact), *use* (consume / extend) - and a **status**:
+
+- `stable` - current and holds.
+- `draft` - exists, rough or incomplete.
+- `to write` - planned; the material exists but is not yet a single doc.
+- `retired` - intentionally not part of the active Buildchain v2 surface.
+
+## Map
+
+| Your question | Document | Plane | Status |
+| --- | --- | --- | --- |
+| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |
+| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |
+| How do I install or run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |
+| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
+| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
+| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |
+| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |
+| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |
+| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
+| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
+| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
+| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
+| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md) | use | stable |
+| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md) | verify | stable |
+| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |
+| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |
+
+## Also asking about
+
+- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)
+  and [`migration-inventory.md`](migration-inventory.md).
+- **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->
+  [`release-governance.md`](release-governance.md) and
+  [`release-flow.md`](release-flow.md).
+- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)
+  and [`release-flow.md`](release-flow.md).
+- **pnpm / npm / yarn / package-manager adapters** ->
+  [`lifecycle-protocol.md`](lifecycle-protocol.md).
+- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)
+  and [`reusable-build-surface.md`](reusable-build-surface.md).
+- **libnode / native artifacts / self-hosted runner matrix** ->
+  [`reusable-build-surface.md`](reusable-build-surface.md) and
+  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).
+- **Trusted Publishing / npm / publish evidence / recovery** ->
+  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
+- **sites / web previews / staging / production gates** ->
+  [`web-surface-deployments.md`](web-surface-deployments.md).
+
+## How this map is maintained
+
+- A document becomes a row here when it is a stable entrypoint for a user,
+  contributor, or workflow consumer.
+- A row's status must never claim more than the artifact delivers.
+- `why` documents explain intent and design pressure; `verify` and `use`
+  documents should state what is guaranteed, where to verify it, and the current
+  maturity of that guarantee.

package/docs/lifecycle-protocol.md

@@ -189,7 +189,8 @@ node scripts/write-publish-evidence.mjs
 ```
 
 When `actions/promote-buildchain-ref` runs with `publish-transaction: "true"`,
-the publish stage receives:
+the publish stage receives the transaction identity plus the resolved publish
+contract:
 
 ```text
 BUILDCHAIN_VERSION
@@ -202,6 +203,11 @@ BUILDCHAIN_RELEASE_SHA
 BUILDCHAIN_RELEASE_MATERIAL_SHA
 BUILDCHAIN_PUBLISH_TOOLING_SHA
 BUILDCHAIN_PUBLISH_EVIDENCE
+BUILDCHAIN_PUBLISH_MODE
+BUILDCHAIN_PUBLISH_AUTH
+BUILDCHAIN_NPM_DIST_TAG
+BUILDCHAIN_PACKAGE_SET_ORDER
+BUILDCHAIN_PACKAGE_SET_MAIN_PACKAGE
 ```
 
 The stage must write publish evidence JSON. Buildchain validates that evidence
@@ -212,6 +218,20 @@ without local workspace residue. See
 [`docs/publish-transaction.md`](publish-transaction.md) for the state machine,
 evidence schema, and recovery commands.
 
+For npm packages, prefer:
+
+```toml
+[publish]
+mode = "publish-final-version"
+auth = "trusted-publishing"
+dist_tag = "latest"
+```
+
+Use `mode = "promote-existing-version"` only for explicit same-version
+dist-tag recovery, and pair it with `auth = "npm-token"`. Trusted Publishing
+does not authorize `npm dist-tag add`; Buildchain fails that combination before
+any publish transaction side effect.
+
 ## Promotion Semantics
 
 `actions/promote-buildchain-ref` consumes `version.files`, `lifecycle.verify`,

package/docs/migration-inventory.md

@@ -0,0 +1,88 @@
+# Buildchain v2 Migration Inventory
+
+This inventory records the buildchain v2 action surface. Buildchain v2 is the
+monorepo source of truth for active Kungfu repository workflows, the active
+reusable build workflow, and the three GitHub Actions that are still part of
+Buildchain's reusable contract.
+Standalone `workflows` and `action-*` repositories are historical rollback
+anchors, not active Buildchain migration targets.
+
+## Workflow Sources
+
+| Source repository | Previous branch | Buildchain v2 disposition |
+| --- | --- | --- |
+| `workflows` | `dev/v2/v2.0` | root `.github/workflows` sources migrated; reusable workflows linted by actionlint |
+
+## Reusable Workflow Boundaries
+
+The active Buildchain-native reusable surface is:
+
+| Workflow | Disposition |
+| --- | --- |
+| `.github/workflows/.build.yml` | active reusable build contract: runner presets, trusted event gate, publish source lock, lifecycle commands, deterministic artifacts, aggregate summary, and release manifest outputs |
+
+Other hidden reusable workflow files from the old `workflows` repository may
+still exist in `.github/workflows`. They are retained so the repository can lint
+them, document migration boundaries, and make retired paths fail closed. They
+are not new Buildchain v2 integration targets unless a dedicated document says
+otherwise. In particular, the legacy `.release-new-version.yml` path is not the
+modern publish surface; new publish integrations should use `.build.yml`,
+`buildchain.toml`, `lifecycle.publish`, and publish transaction evidence.
+
+## Migrated Actions
+
+No standalone `action-*` repository is shipped as a Buildchain action anymore.
+Old product, operations, PR-helper, page-generation, dependency-sync, and
+version-bump actions have either been retired or absorbed into Buildchain's
+native lifecycle, reusable workflow, and promotion scripts.
+
+## Retired Actions Excluded From v2
+
+These legacy action repositories are intentionally not shipped as buildchain v2
+actions because the corresponding workflows now reject the retired mechanism or
+because the action is part of that retired path.
+
+| Previous repository | Reason |
+| --- | --- |
+| `action-approve` | retired GitHub issue/PR helper; use repository-native GitHub automation |
+| `action-batch-pull-request` | retired PR orchestration helper; not part of the Buildchain reusable contract |
+| `action-bump-version` | replaced by Buildchain release-line scripts and `actions/promote-buildchain-ref` |
+| `action-check-format` | replaced by project-owned `lifecycle.verify` commands |
+| `action-find-dependencies` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-generate-download-page` | retired product page generator; model as project-owned lifecycle/deploy work if needed |
+| `action-generate-release-page` | retired product page generator; model as project-owned lifecycle/deploy work if needed |
+| `action-merge-close-issue` | retired GitHub issue/PR helper; use repository-native GitHub automation |
+| `action-package-dependency` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-publish-prebuilt` | retired S3 prebuilt publisher; use lifecycle publish plus publish transaction evidence |
+| `action-purge-artifacts` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-qa-automated` | retired external QA trigger; model as project-owned lifecycle or workflow logic |
+| `action-release-note` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-rollback-release` | replaced by Buildchain publish transaction recover/finalize/repair semantics |
+| `action-set-collaborators` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-sync-airtable` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-sync-extensions-version` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |
+| `action-sync-pr` | retired PR synchronization helper; not part of the Buildchain reusable contract |
+| `action-update-dependencies-version` | retired dependency-version helper; use package-manager adapters and lifecycle commands |
+
+## Buildchain-Native Actions
+
+These actions are new Buildchain v2 surfaces rather than migrations from an
+older standalone action repository.
+
+| Buildchain path | Purpose |
+| --- | --- |
+| `actions/promote-buildchain-ref` | governance-closed Buildchain release ref promotion |
+| `actions/run-lifecycle` | lifecycle command execution and deterministic artifact manifest generation |
+| `actions/validate-config` | `buildchain.toml` version-state and lifecycle preflight without executing lifecycle commands |
+
+## Stable v2 Refs
+
+- Actions: `kungfu-systems/buildchain/actions/<name>@v2`
+- Reusable workflows: `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v2`
+
+## Verification Gates
+
+- `pnpm install --frozen-lockfile`
+- `pnpm run check`
+- GitHub-hosted `Verify` workflow
+- Manual `Self-hosted Runner Smoke` workflow for trusted self-hosted runner validation

package/docs/ownership.md

@@ -0,0 +1,52 @@
+# Ownership And Migration Rules
+
+## Source Of Truth
+
+Buildchain v2 workflow and action design lands in this repository. Standalone
+`workflows` and `action-*` repositories are historical rollback anchors.
+Buildchain only ships the native action surface required for config validation,
+lifecycle execution, and release ref promotion.
+
+## Compatibility Rule
+
+Do not break existing stable reusable workflow refs during migration:
+
+- `kungfu-systems/workflows@v2`
+
+Any consumer migration must record:
+
+- old `uses:` refs;
+- new `uses:` refs;
+- workflow run ids;
+- rollback command or revert path.
+
+New stable references should use:
+
+- `kungfu-systems/buildchain/actions/validate-config@v2`
+- `kungfu-systems/buildchain/actions/run-lifecycle@v2`
+- `kungfu-systems/buildchain/actions/promote-buildchain-ref@v2`
+- `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v2`
+
+## Publishing Rule
+
+Publishing paths stay disabled in buildchain's own verification workflows unless
+explicitly enabled by a production release workflow. Any consumer cutover that
+publishes packages, S3 artifacts, release pages, or preview links must include
+rollback notes. Reusable workflow consumers should gate publish jobs with
+`needs.<build-job>.outputs.publish-allowed == 'true'` and record the requested
+`publish-channel`, rather than duplicating channel branch logic in every
+consumer workflow.
+
+## Candidate Ref Rule
+
+Candidate refs are expected to resolve under `kungfu-systems/*`. Broader
+sources require an explicit trust decision before they can reach self-hosted
+runners or secrets.
+
+## Source-Locked Publish Rule
+
+When a consumer uses `publish-gate/*` branches, publish jobs must use the
+resolved `publish-source-sha` and `release-manifest-json` emitted by the reusable
+build workflow. Before touching a package registry, S3 bucket, release page, or
+floating alias, the publish job must verify that the gate branch still points at
+the recorded SHA. A moved gate branch is a stale release decision, not a retry.

package/docs/publish-transaction.md

@@ -70,6 +70,13 @@ of reusing or overwriting that failed transaction slot.
 Repositories declare publish work in `buildchain.toml`:
 
 ```toml
+[publish]
+mode = "publish-final-version"
+auth = "trusted-publishing"
+dist_tag = "latest"
+package_set_order = "platforms-first-main-last"
+main_package = "@kungfu-tech/libnode"
+
 [lifecycle.publish]
 commands = [
   "python scripts/publish_wheels.py",
@@ -93,6 +100,11 @@ BUILDCHAIN_RELEASE_SHA
 BUILDCHAIN_RELEASE_MATERIAL_SHA
 BUILDCHAIN_PUBLISH_TOOLING_SHA
 BUILDCHAIN_PUBLISH_EVIDENCE
+BUILDCHAIN_PUBLISH_MODE
+BUILDCHAIN_PUBLISH_AUTH
+BUILDCHAIN_NPM_DIST_TAG
+BUILDCHAIN_PACKAGE_SET_ORDER
+BUILDCHAIN_PACKAGE_SET_MAIN_PACKAGE
 ```
 
 Buildchain itself uses this contract for npm publishing:
@@ -103,7 +115,7 @@ command = "node scripts/npm-publish-transaction.mjs"
 ```
 
 That script validates that `package.json` matches `BUILDCHAIN_VERSION`, runs
-`npm publish --access public --tag <alpha|latest>` through npm Trusted
+`npm publish --access public --tag <BUILDCHAIN_NPM_DIST_TAG>` through npm Trusted
 Publishing, and writes npm artifact evidence before the promotion action moves
 public refs.
 
@@ -111,6 +123,33 @@ public refs.
 match. `BUILDCHAIN_PUBLISH_TOOLING_SHA` identifies the publishing code. A repair
 run may change tooling, but material drift fails closed.
 
+## Release Modes And Auth
+
+Buildchain distinguishes two npm release modes:
+
+| Mode | Use | Auth | npm operation |
+| --- | --- | --- | --- |
+| `publish-final-version` | normal alpha or stable publication | `trusted-publishing` | `npm publish --tag <alpha|latest>` |
+| `promote-existing-version` | same-version alpha-to-latest recovery | `npm-token` | `npm dist-tag add <pkg>@<version> latest` |
+
+The normal libnode path is `publish-final-version`: publish an alpha package set
+such as `22.22.3-kf.3-alpha.0` with the `alpha` dist-tag, then publish a
+distinct final package set such as `22.22.3-kf.3` with the `latest` dist-tag.
+GitHub-hosted npm Trusted Publishing can authorize those `npm publish` calls
+when the workflow grants `id-token: write`.
+
+`promote-existing-version` is deliberately separate. npm Trusted Publishing does
+not authorize arbitrary registry-management operations such as `npm dist-tag
+add`; it authorizes publish-time package provenance. Therefore same-version
+promotion must declare `auth = "npm-token"`. Buildchain runs an npm token
+preflight with `npm whoami` before it writes any release transaction state or
+moves a dist-tag. Missing token auth fails early with a contract error instead
+of a late `E401` after publish evidence has started to move.
+
+For package sets, `package_set_order = "platforms-first-main-last"` makes the
+main package the visibility gate. Platform package side effects are planned or
+retried first, and the main package or main dist-tag move happens last.
+
 ## Evidence
 
 The publish lifecycle must write JSON evidence. Buildchain validates common