@kungfu-tech/buildchain 2.8.0 → 2.8.1

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

@@ -214,6 +214,19 @@ contract-world witness JSON paths when released artifacts must prove
 byte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from
 `@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the
 result under the KFD-provided `kfd-1` passport section.
+Set `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public
+release trust claim JSON paths when a release makes additional human/agent
+visible claims. Buildchain requires each public claim to bind declared sources,
+machine-readable evidence, hashes, artifact coordinates, verification results,
+audit boundary, responsibility state, and residual risk. Unbound claims fail
+passport verification; prose-only claims downgrade the KFD-2 audit.
+Set `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3
+collaboration-interface pre-build witness paths, then provide artifact-side
+evidence with `release-passport-kfd-3-artifact-witness-jsons` or a
+product-owned `release-passport-kfd-3-artifact-verify-command` such as
+`kungfu agent verify --json`. Buildchain compares declared shipped public
+surfaces with artifact-exposed public surfaces and writes the result under the
+KFD-provided `kfd-3` passport section.
 When present, the passport includes the aggregate build summary, platform
 artifact manifests, npm publish evidence, dist-tag promotion evidence, the
 release-state ref, trusted publishing metadata, and the Buildchain transaction

package/bin/buildchain.mjs

@@ -77,6 +77,10 @@ function usage() {
                                     [--platform-manifest-json <json-or-path>]...
                                     [--dist-tag-evidence-json <json-or-path>]
                                     [--kfd-1-witness-json <json-or-path>]...
+                                    [--kfd-2-claim-json <json-or-path>]...
+                                    [--kfd-3-prebuild-witness-json <json-or-path>]...
+                                    [--kfd-3-artifact-witness-json <json-or-path>]...
+                                    [--kfd-3-artifact-verify-cmd <command>]
                                     [--release-extra-json <json-or-path>]
                                     [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
   buildchain verify release-passport <file-or-url> [--json]
@@ -736,6 +740,10 @@ async function main(argv = process.argv.slice(2)) {
       platformManifestJsons: readRepeatedFlag(collectArgs, "platform-manifest-json"),
       distTagEvidenceJson: readFlag(collectArgs, "dist-tag-evidence-json", ""),
       kfd1WitnessJsons: readRepeatedFlag(collectArgs, "kfd-1-witness-json"),
+      kfd2ClaimJsons: readRepeatedFlag(collectArgs, "kfd-2-claim-json"),
+      kfd3PrebuildWitnessJsons: readRepeatedFlag(collectArgs, "kfd-3-prebuild-witness-json"),
+      kfd3ArtifactWitnessJsons: readRepeatedFlag(collectArgs, "kfd-3-artifact-witness-json"),
+      kfd3ArtifactVerifyCommand: readFlag(collectArgs, "kfd-3-artifact-verify-cmd", ""),
       releaseJsonExtra: readFlag(collectArgs, "release-extra-json", ""),
       publishJson: readFlag(collectArgs, "publish-json", ""),
       workflow,

package/dist/site/agent-index.json

@@ -7,7 +7,8 @@
     "release-model.json",
     "cli-registry.json",
     "workflow-registry.json",
-    "artifact-schemas.json"
+    "artifact-schemas.json",
+    "buildchain-contract.json"
   ],
   "instruction": "Use this bundle as the package-owned fact source for Buildchain pages. Do not infer current release mechanics from prose alone."
 }

package/dist/site/artifact-schemas.json

@@ -19,6 +19,7 @@
     "workflow-registry.json",
     "release-model.json",
     "artifact-schemas.json",
+    "buildchain-contract.json",
     "product-mechanism.json",
     "release-provenance.json",
     "agent-index.json"

package/dist/site/buildchain-contract.json

@@ -0,0 +1,298 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-runtime-contract-world",
+  "product": {
+    "name": "Buildchain",
+    "package": "@kungfu-tech/buildchain",
+    "version": "2.8.1",
+    "repository": "https://github.com/kungfu-systems/buildchain"
+  },
+  "majorLine": "v2",
+  "compatibilityPolicy": "major-compatible",
+  "surfaces": [
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "reusable-build",
+      "kind": "workflow",
+      "path": ".github/workflows/.build.yml",
+      "publicRef": "kungfu-systems/buildchain/.github/workflows/.build.yml@v2",
+      "requiredInputs": [],
+      "requiredOutputs": [
+        "buildchain-runtime-sha",
+        "publish-source-sha",
+        "build-summary-artifact",
+        "release-candidate-artifact"
+      ],
+      "breakingDefaults": {
+        "buildchainRefDefault": "workflow-shell-ref-or-v2",
+        "promoteOnlyHeavyBuildPolicy": "pr-stage-only"
+      },
+      "optionalInputs": [
+        "buildchain-ref",
+        "runner-preset",
+        "platforms-json",
+        "release-candidate",
+        "artifact-transfer-mode",
+        "buildchain-contract-lock-path",
+        "buildchain-contract-drift-issue-mode"
+      ],
+      "guarantees": [
+        "runtime floating refs are resolved to immutable SHAs before matrix jobs",
+        "publish source locks are verified before heavy build jobs",
+        "release-candidate builds do not publish registry artifacts",
+        "contract drift is checked before heavy build jobs for stable floating refs"
+      ],
+      "breakingDigest": "sha256:6303aa2c2cb8c2cef4301ceea95cc3c426c2aa81d98714aa9bdf2471d63faee1",
+      "auditDigest": "sha256:93f8e59720cdfc8de2d04c1e76933932a28dfbaec80c26a5cf4266c85199322c"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "release-candidate-promote",
+      "kind": "workflow",
+      "path": ".github/workflows/release-candidate-promote.yml",
+      "publicRef": "kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2",
+      "requiredInputs": [
+        "channel"
+      ],
+      "requiredOutputs": [
+        "promoted-sha",
+        "built-source-sha",
+        "release-candidate-artifact"
+      ],
+      "breakingDefaults": {
+        "promoteOnlyReleaseCandidate": true,
+        "requiredStatusCheck": "check"
+      },
+      "optionalInputs": [
+        "buildchain-ref",
+        "release-candidate-workflow-file",
+        "release-candidate-workflow-name",
+        "publish-required-artifacts-json",
+        "release-passport-kfd-1-witness-jsons",
+        "release-passport-kfd-2-claim-jsons",
+        "release-passport-kfd-3-prebuild-witness-jsons",
+        "release-passport-kfd-3-artifact-witness-jsons",
+        "release-passport-kfd-3-artifact-verify-command",
+        "buildchain-contract-lock-path",
+        "buildchain-contract-drift-issue-mode"
+      ],
+      "guarantees": [
+        "promotion reuses PR-stage release-candidate artifacts",
+        "promotion does not run the heavy native build matrix",
+        "built source and promotion channel SHA are recorded separately",
+        "contract drift is checked before release-candidate resolution and publish",
+        "publish-gate source locks are created by the wrapper and enforced by promote-buildchain-ref before publish side effects"
+      ],
+      "breakingDigest": "sha256:1c27595adaa8fbc334b3f7f66605e4544cb8c60ce81a9bb7ee94d6ede93c65ac",
+      "auditDigest": "sha256:4fddfd83cd8a90c45c1356561f38985b5a29f1cdb04ca969639867b6ee6869d0"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "promote-buildchain-ref-action",
+      "kind": "action",
+      "path": "actions/promote-buildchain-ref/action.yml",
+      "publicRef": "kungfu-systems/buildchain/actions/promote-buildchain-ref@v2",
+      "requiredInputs": [
+        "token",
+        "sha",
+        "target-ref"
+      ],
+      "requiredOutputs": [
+        "sha"
+      ],
+      "breakingDefaults": {
+        "requireGovernance": false,
+        "releasePassport": true
+      },
+      "optionalInputs": [
+        "publish-transaction",
+        "publish-required-artifacts-json",
+        "promote-only-release-candidate",
+        "release-passport-kfd-1-witness-jsons",
+        "release-passport-kfd-2-claim-jsons",
+        "release-passport-kfd-3-prebuild-witness-jsons",
+        "release-passport-kfd-3-artifact-witness-jsons",
+        "release-passport-kfd-3-artifact-verify-command"
+      ],
+      "guarantees": [
+        "protected release refs and durable release-state are finalized by Buildchain",
+        "release passport finalization is idempotent after publish side effects",
+        "publish transactions can require a resolved publish-gate source lock to prevent floating-ref drift"
+      ],
+      "breakingDigest": "sha256:fca97ba00248ed436695f12f8fc44404458af462e666aa7b69b4315b32705bdd",
+      "auditDigest": "sha256:014233a4add8a01fbccc40c86821c54d3aa12cd3b1158423ac88cb0e45a352a8"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "report-buildchain-issue-action",
+      "kind": "action",
+      "path": "actions/report-buildchain-issue/action.yml",
+      "publicRef": "kungfu-systems/buildchain/actions/report-buildchain-issue@v2",
+      "requiredInputs": [
+        "token"
+      ],
+      "requiredOutputs": [
+        "ok",
+        "action",
+        "issue-url",
+        "fingerprint"
+      ],
+      "breakingDefaults": {
+        "failOnError": false,
+        "mode": "create-or-comment"
+      },
+      "optionalInputs": [
+        "report-kind",
+        "target-repository",
+        "body-file",
+        "comment-cooldown-hours"
+      ],
+      "guarantees": [
+        "issue reporting is fail-soft by default",
+        "GitHub API 429 and 5xx failures are retried",
+        "missing issue permissions produce a copyable summary fallback"
+      ],
+      "breakingDigest": "sha256:575a2cb02cdb2e61bb2e84d5bbaaf64b430aa5d7936645660b592de4549d81b0",
+      "auditDigest": "sha256:512ccfeb7deedd950da87b112d25aa8667e081775b3b604f121374d25420eec1"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "release-passport-schema",
+      "kind": "schema",
+      "path": "packages/core/release-passport.js",
+      "requiredInputs": [
+        "buildchain.release.json"
+      ],
+      "requiredOutputs": [
+        "check-report.json"
+      ],
+      "breakingDefaults": {
+        "schemaVersion": 1,
+        "contract": "kungfu-buildchain-release-passport"
+      },
+      "guarantees": [
+        "release passport verification fails closed for malformed required evidence",
+        "release-state SHA is recorded as a durable audit entrance"
+      ],
+      "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
+      "auditDigest": "sha256:9668f3e01cfe8ce5b94ebdda24aeeaddbd609d8f4cc7cca33d82cbc59aae66f5"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "kfd-1-release-gate",
+      "kind": "schema",
+      "path": "packages/core/kfd-gate.js",
+      "requiredInputs": [
+        "KFD-1 witness JSON"
+      ],
+      "requiredOutputs": [
+        "kfd-1 release gate evidence"
+      ],
+      "breakingDefaults": {
+        "witnessContract": "kungfu-buildchain-kfd-1-witness-set",
+        "releaseGateContract": "kungfu-buildchain-kfd-1-release-gate"
+      },
+      "guarantees": [
+        "KFD-1 witnesses must include at least one artifact byte surface",
+        "artifact bytes are sha256 checked before passport finalization succeeds",
+        "KFD self contract witnesses record source/artifact hashes, self-hosting boundary, and responsibility state"
+      ],
+      "breakingDigest": "sha256:f46c1f67b94957ad956cf70db59a73fd5690bd67c91edf9c2d0eb8f3d1e3cf8d",
+      "auditDigest": "sha256:6a99ee108c385837ee9f1dbb75848f6ea434b6474977e6e567ae81f8fc9a555c"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "kfd-2-release-trust-passport-audit",
+      "kind": "schema",
+      "path": "packages/core/release-passport.js",
+      "requiredInputs": [
+        "public release claim evidence"
+      ],
+      "requiredOutputs": [
+        "kfd-2 release trust passport audit"
+      ],
+      "breakingDefaults": {
+        "releaseTrustPassportContract": "kungfu-buildchain-kfd-2-release-trust-passport-audit"
+      },
+      "guarantees": [
+        "public release claims must bind declared sources, machine evidence, hashes, artifacts, verification, audit boundary, responsibility, and residual risk",
+        "unbound public claims fail release passport verification",
+        "prose-only public claims downgrade the release trust passport audit"
+      ],
+      "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
+      "auditDigest": "sha256:9668f3e01cfe8ce5b94ebdda24aeeaddbd609d8f4cc7cca33d82cbc59aae66f5"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "kfd-3-collaboration-interface-release-gate",
+      "kind": "schema",
+      "path": "packages/core/kfd-gate.js",
+      "requiredInputs": [
+        "KFD-3 prebuild witness JSON",
+        "KFD-3 artifact witness JSON or verify command"
+      ],
+      "requiredOutputs": [
+        "kfd-3 collaboration-interface release gate evidence"
+      ],
+      "breakingDefaults": {
+        "prebuildWitnessContract": "kungfu-buildchain-kfd-3-collaboration-interface-prebuild-witness",
+        "artifactWitnessContract": "kungfu-buildchain-kfd-3-collaboration-interface-artifact-witness",
+        "releaseGateContract": "kungfu-buildchain-kfd-3-collaboration-interface-release-gate"
+      },
+      "guarantees": [
+        "KFD-3 pre-build witnesses must declare participant-facing public surfaces",
+        "artifact witnesses must not expose undeclared public participant-facing surfaces",
+        "collaborationInterface.digest mismatches fail passport verification",
+        "KFD repository self-verification can declare docs, schemas, standards metadata, package exports, and site-consumption contracts",
+        "KFD-3 passports expose releaseStatus, witness hashes, declared capability verification, reverse audit boundary, residual risk, and responsibility state"
+      ],
+      "breakingDigest": "sha256:33654f3444c893754aacc42dde3051f0a371bd17c6ef7c657c579a07159cd7c1",
+      "auditDigest": "sha256:6a99ee108c385837ee9f1dbb75848f6ea434b6474977e6e567ae81f8fc9a555c"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "buildchain-cli",
+      "kind": "cli",
+      "path": "bin/buildchain.mjs",
+      "requiredInputs": [],
+      "requiredOutputs": [],
+      "breakingDefaults": {
+        "binary": "buildchain",
+        "moduleSystem": "esm"
+      },
+      "optionalInputs": [
+        "validate",
+        "lifecycle",
+        "collect github-release",
+        "verify release-passport",
+        "release-propagation",
+        "infra-contract"
+      ],
+      "guarantees": [
+        "CLI commands are stable within the major line unless the contract major changes"
+      ],
+      "breakingDigest": "sha256:097db3e67509bedda8c6548bf1edfbfcf57f7b5510520b6a7b7e078d7ec087c8",
+      "auditDigest": "sha256:478e656104272675d3be3391158251472e0c2515b3113376ef0e52757b47ace0"
+    }
+  ],
+  "compatibilityDigest": "sha256:ca668f3f73ab0d84db0d489efccf6cd556704b069990a37a0c6c77a6519f754b",
+  "contractDigest": "sha256:f76f0c5dfd89f5a27ce2a00c2cc15779baa22dc2ee2b13dd69e62ee7ffda5731"
+}

package/dist/site/release-provenance.json

@@ -11,6 +11,7 @@
       ".": "./packages/core/index.js",
       "./core": "./packages/core/index.js",
       "./artifact-passport": "./packages/core/artifact-passport.js",
+      "./buildchain-contract": "./packages/core/buildchain-contract.js",
       "./diagnostics": "./packages/core/diagnostics.js",
       "./issue-reporting": "./packages/core/issue-reporting.js",
       "./logging": "./packages/core/logging.js",
@@ -24,6 +25,7 @@
       "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
       "./site/release-model.json": "./dist/site/release-model.json",
       "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
+      "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",
       "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
       "./site/release-provenance.json": "./dist/site/release-provenance.json",
       "./site/agent-index.json": "./dist/site/agent-index.json",

package/docs/MAP.md

@@ -34,6 +34,9 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
 | How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |
+| How do I audit public KFD-2 release trust claims? | [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |
+| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |
+| How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |
 | How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
 | How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |
 | Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |
@@ -93,6 +96,12 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`release-propagation.md`](release-propagation.md).
 - **KFD-1 contract worlds / byte-for-byte release gates** ->
   [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).
+- **KFD-2 public release trust claim audit** ->
+  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).
+- **KFD-3 collaboration-interface / agent-facing control surface closure** ->
+  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).
+- **floating `@v2` / contract lock / compatible drift issue** ->
+  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).
 - **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->
   [`release-passport.md`](release-passport.md),
   [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).

package/docs/cli.md

@@ -261,6 +261,9 @@ buildchain collect github-release \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
   --dist-tag-evidence-json .buildchain/release-evidence/v2.3.2/dist-tag-evidence.json \
   --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \
+  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \
+  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \
+  --kfd-3-artifact-verify-cmd "kungfu agent verify --json" \
   --release-extra-json '{"channel":"release","targetRef":"release/v2/v2.3"}' \
   --output-dir .buildchain/release-passport
 ```
@@ -286,6 +289,42 @@ the KFD-provided top-level key currently named `kfd-1`. Consumers should not
 duplicate this by running repository-specific scripts or invoking the Kungfu
 SDK from their release workflow.
 
+For the KFD repository, KFD-1 witnesses may be self-hosted standard-contract
+witnesses: docs, schemas, standards metadata, package exports, and
+site-consumption entrypoints are checked from source hashes to packaged artifact
+hashes, and the passport records schema IDs, self-hosting boundary, result, and
+responsibility state.
+
+`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2
+release trust passport audit. Buildchain also derives KFD-2 claims from KFD-1
+and KFD-3 gate evidence. Public claims must bind declared sources,
+machine-readable evidence, hashes, artifact coordinates, verification results,
+audit boundary, responsibility state, and residual risk. Unbound claims fail
+passport verification; prose-only claims downgrade the KFD-2 audit and emit a
+warning.
+
+`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface
+release gate. The product remains the source of truth: it emits a pre-build
+witness that contains or points to its KFD-3 collaboration interface, declared
+participant-facing public surfaces, and registry digest. Buildchain freezes
+that declaration before publication. The artifact side is supplied either by
+`--kfd-3-artifact-witness-json` or by a product-owned command such as
+`--kfd-3-artifact-verify-cmd "kungfu agent verify --json"`. Buildchain then
+checks closure: every declared shipped public surface must be present in the
+artifact witness, and every artifact-exposed participant-facing public surface
+must have been declared. The generated passport writes this evidence under the
+KFD-provided top-level key currently named `kfd-3`.
+
+This gate is useful for agent-facing products because it turns KFD-3 from prose
+into release evidence. A package cannot claim KFD-3 collaboration-interface
+support merely because the docs mention it; the release passport must show the
+frozen declaration, the artifact-side witness digest, and a passing closure
+comparison.
+For the KFD repository itself, the witness can declare docs, schemas, standards
+metadata, package exports, and site-consumption contracts as grouped public
+surfaces; the artifact witness must expose the same enumerable package/site
+surfaces or verification fails closed.
+
 `--impact-json` supplies the surface-aware impact ledger. Production release
 passports (`release/*`) and major publish-gate passports require
 `surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it

package/docs/migration-inventory.md

@@ -30,6 +30,13 @@ and 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.
 
+Release templates that previously performed direct publishing or deployment are
+now fail-closed when retained for compatibility discovery. They do not call
+legacy publish actions, `npm publish`, or deploy providers directly. Callers must
+migrate to `release-candidate-promote.yml@v2` or a project-owned
+`lifecycle.publish` command behind a publish-gate source lock, so floating
+`@v2` consumers cannot bypass source-lock drift protection.
+
 ## Migrated Actions
 
 No standalone `action-*` repository is shipped as a Buildchain action anymore.
@@ -73,6 +80,10 @@ These legacy workflow entrypoints are intentionally not shipped from the root
 | Previous workflow | Reason |
 | --- | --- |
 | `.batch-pull-request.yml` | retired PR orchestration helper; v2.5 dev integration governance will use a new protected-dev PR protocol instead |
+| `.release-new-version.yml` | retained as a fail-closed compatibility stub; direct publish model replaced by source-locked release-candidate promotion |
+| `.release-elastic-beanstalk.yml` | retained as a fail-closed compatibility stub; deploy side effects must move behind project lifecycle publish and publish-gate source locks |
+| `.sam-release.yml` | retained as a fail-closed compatibility stub; deploy side effects must move behind project lifecycle publish and publish-gate source locks |
+| `.wheel-release.yml` | retained as a fail-closed compatibility stub; package publish side effects must move behind project lifecycle publish and publish-gate source locks |
 
 ## Buildchain-Native Actions
 

package/docs/release-candidate.md

@@ -68,7 +68,12 @@ build summary by the configured `artifact-name` before promotion. It also
 downloads payload artifacts from the same PR-stage run, validates the required
 payload count, passes downloaded platform manifests into the release passport,
 and either forwards an explicit `publish-required-artifacts-json` value or
-generates one before calling `promote-buildchain-ref`. The default npm path
+generates one before calling `promote-buildchain-ref`. Before that call, the
+wrapper creates or updates `publish-gate/{alpha,release,major}` to the
+promotion channel commit and passes that ref, target SHA, and `locked=true` to
+the promote action with `require-publish-source-lock: "true"`. Consumers using
+floating `@v2` therefore get publish-side source-lock drift protection without
+copying resolver or promote YAML. The default npm path
 generates that requirement list from the downloaded `.tgz` payloads themselves:
 Buildchain reads `package/package.json` inside each tarball for the real scoped
 package name and version, computes npm-style `sha512-...` integrity over the
@@ -76,3 +81,35 @@ tarball bytes, marks `publish-package-main` as `role: main`, and marks every
 other package as `role: platform`. Consumer workflows therefore stay
 declarative and do not need their own artifact download or publish-evidence
 generation scripts.
+
+When `github-release: true`, the wrapper also owns the GitHub Release side of
+the publish model. Once the release transaction is complete, it creates or
+updates the exact-tag GitHub Release, applies prerelease/latest metadata from
+the semver tag, and uploads the publish evidence file together with the
+generated release passport assets. This keeps npm/registry publication,
+Buildchain release passport persistence, and `release.published` propagation in
+one declarative reusable workflow.
+
+Products that publish KFD release trust evidence can keep that path declarative
+too. Pass KFD-1 self contract witnesses, KFD-2 public claim files, and KFD-3
+pre-build/artifact evidence into the wrapper:
+
+```yaml
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2
+    with:
+      channel: alpha
+      artifact-name: libnode
+      github-release: true
+      release-passport-kfd-1-witness-jsons: .buildchain/kfd-1/standard-contract.witness.json
+      release-passport-kfd-2-claim-jsons: .buildchain/kfd-2/release-claims.json
+      release-passport-kfd-3-prebuild-witness-jsons: .buildchain/kfd-3/collaboration-interface.prebuild.json
+      release-passport-kfd-3-artifact-verify-command: kungfu agent verify --json
+```
+
+Buildchain forwards those declarations into `promote-buildchain-ref`, verifies
+KFD-1 source/artifact contract surfaces, audits KFD-2 public release claims, and
+compares KFD-3 declared shipped public surfaces with artifact-exposed public
+surfaces. The release passport records the results under `kfd-1`, `kfd-2`, and
+the KFD-provided `kfd-3` section.

package/docs/release-governance.md

@@ -425,6 +425,24 @@ consumer repository still owns registry truth: npm, PyPI, OCI, S3, Conan, CMake
 packaging, download pages, dist-tags, and similar side effects must be
 implemented by project lifecycle commands that emit Buildchain publish evidence.
 
+Every Buildchain publish model that can run registry side effects must bind the
+publish entrypoint to an immutable `publish-gate/*` source lock. The reusable
+`release-candidate-promote.yml@v2` wrapper creates or updates that gate ref and
+passes `require-publish-source-lock`, `publish-source-ref`,
+`publish-source-sha`, and `publish-source-locked` to
+`promote-buildchain-ref`. Direct action callers must pass the same four inputs
+from the reusable build outputs. Workflows that only collect passports or run
+dry-run package checks do not move publish refs and are not publish-gate
+publication models.
+
+The same wrapper is the declarative GitHub Release publication entrypoint for
+semver releases. Consumers set `github-release: true`; after the publish
+transaction reaches `complete`, Buildchain creates or updates the exact-tag
+GitHub Release and uploads the generated `buildchain.release.json`,
+release-passport assets, and publish evidence. Semver prerelease tags are marked
+`prerelease=true` and `make_latest=false`; stable semver tags are marked latest.
+This is the supported path for downstream `release.published` propagation.
+
 Buildchain also does not maintain bare exact tags such as `1.0.0`. The supported
 exact release and alpha refs are v-prefixed: