@kungfu-tech/buildchain 2.11.14-alpha.5 → 2.11.14-alpha.6

package/docs/release-flow.md

@@ -53,6 +53,7 @@ for the versioned policy and evidence contract.
 | Exact alpha tag | `v2.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
 | Exact release tag | `v2.0.2` | immutable | audit ref for one production release |
 | Floating alpha tag | `v2.0-alpha` | moves | latest test channel for a minor line |
+| Floating major alpha tag | `v2-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
 | Floating minor tag | `v2.0` | moves | latest production patch on a minor line |
 | Floating major tag | `v2` | moves | selected stable major entrypoint |
 
@@ -68,8 +69,8 @@ refs/tags/v*.*.*
 ```
 
 Do not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain
-must be able to update floating channel tags such as `v2`, `v2.0`, and
-`v2.0-alpha` after the exact tag and publish evidence are valid. A ruleset that
+must be able to update floating channel tags such as `v2`, `v2.0`, `v2.0-alpha`,
+and `v2-alpha` after the exact tag and publish evidence are valid. A ruleset that
 matches all `v*` tags also matches floating tags, so release finalization can
 fail with GitHub protected-ref errors even though the exact release tag and
 published artifacts are already durable.
@@ -77,7 +78,7 @@ published artifacts are already durable.
 The intended governance split is:
 
 - exact tags such as `v2.0.14` and `v2.0.15-alpha.0` are immutable audit refs;
-- floating tags such as `v2`, `v2.0`, and `v2.0-alpha` are mutable channel refs
+- floating tags such as `v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can
   move any exact or floating release refs.
@@ -134,6 +135,7 @@ sequenceDiagram
   Promote->>Promote: write and verify version state
   Promote->>Tags: create or reuse vX.Y.Z-alpha.N
   Promote->>Tags: move vX.Y-alpha
+  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor
   Promote->>Alpha: move alpha/vX/vX.Y
   Promote->>Dev: move dev/vX/vX.Y
 ```
@@ -143,6 +145,7 @@ Result:
 ```text
 vX.Y.Z-alpha.N
 vX.Y-alpha
+vX-alpha when X.Y is the highest published alpha minor
 alpha/vX/vX.Y
 dev/vX/vX.Y
 ```
@@ -177,6 +180,7 @@ sequenceDiagram
   Promote->>Promote: prepare vX.Y.(Z+1)-alpha.0
   Promote->>Tags: create or reuse vX.Y.(Z+1)-alpha.0
   Promote->>Tags: move vX.Y-alpha
+  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor
   Promote->>Alpha: move alpha/vX/vX.Y
   Promote->>Dev: move dev/vX/vX.Y
 ```
@@ -195,6 +199,7 @@ point at the production version-state commit, while:
 ```text
 vX.Y.(Z+1)-alpha.0
 vX.Y-alpha
+vX-alpha when X.Y is the highest published alpha minor
 alpha/vX/vX.Y
 dev/vX/vX.Y
 ```
@@ -235,6 +240,7 @@ It should also prepare:
 ```text
 v2.0.3-alpha.0          exact next alpha tag
 v2.0-alpha              floating alpha tag
+v2-alpha                floating major alpha tag when v2.0 is the highest published alpha minor
 alpha/v2/v2.0           alpha channel branch
 dev/v2/v2.0             development channel branch
 ```

package/docs/release-governance.md

@@ -128,13 +128,14 @@ This is why Buildchain maintains both exact and floating refs:
 - `v2` is the selected stable major-line entrypoint;
 - `v2.0.3-alpha.0` is immutable alpha evidence;
 - `v2.0-alpha` is the latest test channel for the `2.0` line.
+- `v2-alpha` is the latest test channel on the highest published alpha minor in major `2`.
 
 A release does not mean "minor is complete." It means "this patch on this minor
 line is now production."
 
 GitHub repository rules must preserve that distinction. Exact tags such as
 `v2.0.2` and `v2.0.3-alpha.0` should be immutable. Floating channel tags such as
-`v2`, `v2.0`, and `v2.0-alpha` must remain movable by the Buildchain promotion
+`v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` must remain movable by the Buildchain promotion
 token after governance checks and publish evidence pass. A tag ruleset that
 protects every `refs/tags/v*` ref is too broad because it also locks the
 floating channel tags that Buildchain is required to update. Prefer exact-tag
@@ -159,9 +160,12 @@ Buildchain then:
 6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a
    fast-forward update.
 7. Moves `vX.Y-alpha` to the same generated alpha commit.
+8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.
 
 This keeps the test channel self-describing. If a consumer checks out
-`v2.0-alpha`, the manifests and exact alpha tag agree.
+`v2.0-alpha` or `v2-alpha`, the manifests and exact alpha tag agree. The major
+alpha ref removes routine consumer edits when Buildchain opens a newer minor,
+while exact tags and SHAs remain the reproducible audit choice.
 
 If `dev/vX/vX.Y` has already advanced before generated alpha version-state
 bookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the
@@ -201,6 +205,7 @@ Buildchain then:
    `vX.Y.(Z+1)-alpha.0`.
 10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha
     commit.
+11. Moves `vX-alpha` to that next alpha only when this remains the highest published alpha minor.
 
 The production channel and the test channel therefore intentionally diverge
 after release: production stays on the release commit, while alpha/dev continue
@@ -513,6 +518,7 @@ When the loop succeeds, maintainers and consumers can rely on these facts:
   not a hidden manual button;
 - every test channel has an exact alpha tag such as `v2.0.3-alpha.0`;
 - every alpha minor line has a floating tag such as `v2.0-alpha`;
+- every major with a published alpha has a cross-minor floating tag such as `v2-alpha`, owned by its highest published alpha minor;
 - version manifests match the tag visible from the same commit;
 - production releases are derived from the alpha tree that was tested;
 - manual non-dry-run promotion cannot bypass PR review and verification;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.14-alpha.5",
+  "version": "2.11.14-alpha.6",
   "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

@@ -23,7 +23,7 @@ function parseTags(input) {
     : String(input || "").split(",").map((tag) => tag.trim()).filter(Boolean);
   for (const tag of tags) {
     if (
-      !/^v\d+$|^v\d+\.\d+$|^v\d+\.\d+-alpha$|^v\d+\.\d+\.\d+$|^v\d+\.\d+\.\d+-alpha\.\d+$/.test(tag)
+      !/^v\d+$|^v\d+-alpha$|^v\d+\.\d+$|^v\d+\.\d+-alpha$|^v\d+\.\d+\.\d+$|^v\d+\.\d+\.\d+-alpha\.\d+$/.test(tag)
     ) {
       throw new Error(`Unsupported buildchain dry-run tag: ${tag}`);
     }
@@ -42,6 +42,7 @@ function getPromotionRule(targetRef, sourceRef = "") {
       sourceRef: sourceRef || "release/vN/vN.M",
       releasePrefix: nextMajor ? `v${nextMajor}.0` : "v(N+1).0",
       majorTag: nextMajor ? `v${nextMajor}` : "v(N+1)",
+      majorAlphaTag: nextMajor ? `v${nextMajor}-alpha` : "v(N+1)-alpha",
       minorTag: nextMajor ? `v${nextMajor}.0` : "v(N+1).0",
       alphaTag: nextMajor ? `v${nextMajor}.0-alpha` : "v(N+1).0-alpha",
       exactReleasePattern: nextMajor ? `v${nextMajor}.0.0` : "v(N+1).0.0",
@@ -69,6 +70,7 @@ function getPromotionRule(targetRef, sourceRef = "") {
     minor,
     releasePrefix,
     majorTag: `v${major}`,
+    majorAlphaTag: `v${major}-alpha`,
     minorTag: releasePrefix,
     alphaTag: `${releasePrefix}-alpha`,
     sourceRef: channel === "alpha" ? `dev/v${major}/v${major}.${minor}` : `alpha/v${major}/v${major}.${minor}`,
@@ -193,7 +195,10 @@ function explainReleaseLineDryRun({
       kind: "alpha",
       action: "would create or reuse immutable alpha evidence tag",
     });
-    plan.floatingRefs.push({ ref: rule.alphaTag, kind: "tag", action: "would move to alpha version-state commit" });
+    plan.floatingRefs.push(
+      { ref: rule.alphaTag, kind: "tag", action: "would move to alpha version-state commit" },
+      { ref: rule.majorAlphaTag, kind: "tag", action: "would move when this is the highest published alpha minor" },
+    );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to alpha version-state commit" },
       { ref: `dev/v${rule.major}/v${rule.major}.${rule.minor}`, action: "would align dev with the published alpha state" },
@@ -211,6 +216,7 @@ function explainReleaseLineDryRun({
       { ref: rule.minorTag, kind: "tag", action: "would move to production release commit" },
       { ref: rule.majorTag, kind: "tag", action: "would move when no newer minor line owns the major tag" },
       { ref: rule.alphaTag, kind: "tag", action: "would move to next alpha version-state commit" },
+      { ref: rule.majorAlphaTag, kind: "tag", action: "would move when this is the highest published alpha minor" },
     );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to production release commit" },
@@ -234,6 +240,7 @@ function explainReleaseLineDryRun({
       { ref: rule.minorTag, kind: "tag", action: "would move to next-major release commit" },
       { ref: rule.majorTag, kind: "tag", action: "would move to next-major release commit" },
       { ref: rule.alphaTag, kind: "tag", action: "would move to next-major alpha commit" },
+      { ref: rule.majorAlphaTag, kind: "tag", action: "would move to next-major alpha commit" },
     );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to next-major release commit" },

package/scripts/generate-site-bundle.mjs

@@ -872,7 +872,7 @@ function buildSiteBundle() {
     schemaVersion: 1,
     contract: "kungfu-buildchain-release-model",
     exactTags: "v-prefixed exact tags are immutable release records.",
-    floatingTags: "vX, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions.",
+    floatingTags: "vX, vX-alpha, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions; vX-alpha follows the highest minor in major X with a published alpha.",
     channelBranches: ["dev/vX/vX.Y", "alpha/vX/vX.Y", "release/vX/vX.Y", "publish-gate/major"],
     protectedDevelopmentBranches: ["dev/vX/vX.Y"],
     releasePassport: {