@kungfu-tech/buildchain 2.2.1 → 2.2.2-alpha.1

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

@@ -178,6 +178,10 @@ governance semantics:
 - 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;
+- anchored/manual release promotion may differ from that alpha tree only in
+  declared `version.files` and the configured anchor manifest, and only when the
+  checked-out release material has passed `lifecycle.verify` or the explicit
+  `verification-command`;
 - 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.

package/docs/lifecycle-protocol.md

@@ -250,6 +250,17 @@ After that PR lands, Buildchain verifies that the version-state PR changed only
 declared version files from the legal channel-promotion parent before it moves
 tags.
 
+For `version.strategy = "anchored"` with `version.next = "manual"`, release
+promotion does not generate a Buildchain-owned version-state commit. In that
+mode, a protected `alpha -> release` PR may carry the declared `version.files`
+from the tested alpha package version to the final package version, and may
+carry the configured `version.manifest` with it. Buildchain only accepts that
+release tree difference when the PR is the valid channel-promotion PR, the
+changed paths are limited to those declared version files plus the anchor
+manifest, and `lifecycle.verify` or `verification-command` has validated the
+checked-out release material. Any code or undeclared file change still fails the
+release tree gate.
+
 The action input `verification-command` remains supported. When it is provided,
 it overrides `lifecycle.verify` for that invocation.
 

package/docs/release-flow.md

@@ -129,7 +129,7 @@ sequenceDiagram
   Promote->>Promote: validate same-repo merged PR
   Promote->>Promote: find same-patch alpha tag
   Promote->>Promote: compare release tree with tested alpha tree
-  Promote->>Promote: write and verify final version state
+  Promote->>Promote: write final version state or verify anchored material
   Promote->>Tags: create or reuse vX.Y.Z
   Promote->>Tags: move vX.Y
   Promote->>Tags: move vX when eligible
@@ -242,7 +242,9 @@ Promotion should stop before moving refs when:
 - the PR was not merged;
 - the branch pair is not a valid channel path;
 - the required status check did not pass;
-- a release tree does not match the same-patch alpha tag tree;
+- a release tree does not match the same-patch alpha tag tree, except for the
+  declared anchored/manual version files and anchor manifest that
+  `lifecycle.verify` or `verification-command` validates;
 - version-state verification fails;
 - a required exact tag already exists at a commit unrelated to the active
   transaction or finalized channel head.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.2.1",
+  "version": "2.2.2-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/release-line-dry-run.js

@@ -217,7 +217,7 @@ function explainReleaseLineDryRun({
       { ref: `alpha/v${rule.major}/v${rule.major}.${rule.minor}`, action: "would move to next alpha version-state commit" },
       { ref: `dev/v${rule.major}/v${rule.major}.${rule.minor}`, action: "would move to next alpha version-state commit" },
     );
-    plan.governanceChecks.push("release source tree must match the same-patch exact alpha tag tree except generated version-state files");
+    plan.governanceChecks.push("release source tree must match the same-patch exact alpha tag tree except generated version-state files or anchored/manual version material");
     plan.versionState.targetVersions = [
       exactRelease.replace(/^next v?/, "").replace(/^v/, ""),
       exactAlpha.replace(/^next v?/, "").replace(/^v/, ""),