@kungfu-tech/buildchain 2.8.8-alpha.0 → 2.8.8-alpha.2

package/dist/site/site-manifest.json

@@ -127,7 +127,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:02e1be97935c0d9520ea22e8ef0dc61d9b860c347f07127074600cdca02713ce"
+      "digest": "sha256:4d1ab96137beea2497b838018dcce793081c09dbcbbfd8ed2123cc58749f95cb"
     },
     {
       "id": "reusable-build-surface",
@@ -135,7 +135,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:8c3e7a5e099c8eb0715bb6f58af90d261f8cb83d384f3281b8763f340277582b"
+      "digest": "sha256:aae753c7fcf4bcb13c08af7b31cc83d898d36e41248b5f710ecee61035de3e8e"
     },
     {
       "id": "publish-transaction",
@@ -143,7 +143,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:dd45cf98f0847e3968f150a09bed84aa1f59cb2687ac988e9519f08dc9c91877"
+      "digest": "sha256:d4758e222935f595f7d8a73fe2c33383898c0f760c5e5051c4f772db06491e7c"
     },
     {
       "id": "release-governance",
@@ -151,7 +151,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:c7348c64e83ea1d154955e2fc0f7318a1c5582a3dfa6bdc5728958ddb418e92d"
+      "digest": "sha256:53c969c38ede9c68e279ca191f2d5661e1d943225d7faa798179569670434ef9"
     },
     {
       "id": "release-flow",

package/docs/lifecycle-protocol.md

@@ -244,11 +244,13 @@ version-state files changed. This prevents verification from quietly adding
 extra source changes to the release commit.
 
 On protected alpha and release branches, the generated version-state commit is
-merged through a normal pull request. This keeps review requirements,
-conversation resolution, strict status checks, and admin enforcement intact.
-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.
+applied by the promotion automation after the reviewed channel PR has merged.
+Buildchain keeps review requirements, conversation resolution, strict status
+checks, and admin enforcement for human channel changes, but adds the
+authenticated promotion token user or app to the managed bypass allowlist for
+generated release bookkeeping. If the direct generated update is rejected,
+promotion fails with a token/protection diagnostic instead of asking humans to
+review a post-publish version-state PR.
 
 For `version.strategy = "anchored"` with `version.next = "manual"`, release
 promotion does not generate a Buildchain-owned version-state commit. In that

package/docs/publish-transaction.md

@@ -285,18 +285,22 @@ When publish transactions are enabled, promotion order is:
 7. move floating tags and channel refs;
 8. mark the transaction `complete`.
 
-If protected branches require a generated version-state PR, the transaction can
-stop in `finalizing` and output `finalization-needed=true`. A later run can
-resume from the same transaction state and complete ref movement without
-republishing matching artifacts.
+If protected branch finalization is interrupted after publish evidence is
+valid, the transaction can stop in `finalizing` and output
+`finalization-needed=true`. A later run resumes from the same transaction state
+and completes ref movement without republishing matching artifacts. New
+Buildchain-managed promotions must finish generated version-state bookkeeping
+with the promotion token directly; they must not require a post-publish human
+PR.
 
 If finalization fails after an exact Git tag, a channel branch, or dev/alpha
 sync ref has already moved, the next run reads the durable `finalizing` state
 and continues from the recorded transaction. The current workflow SHA may be a
-version-state merge commit that contains or corresponds to the transaction's
-`release_material_sha`; it does not have to equal the original `source_sha` or
-the transaction `release_sha`. Exact tags are accepted when they already point
-at the transaction release/material SHA or the finalized channel head. Floating
+generated version-state commit, or a historical version-state merge commit, that
+contains or corresponds to the transaction's `release_material_sha`; it does not
+have to equal the original `source_sha` or the transaction `release_sha`. Exact
+tags are accepted when they already point at the transaction release/material
+SHA or the finalized channel head. Floating
 channel tags and dev/alpha refs are then retried idempotently, and the
 transaction is marked `complete` only after those public refs are consistent.
 Writing `complete` clears any stale `failure` value from earlier attempts, so

package/docs/release-governance.md

@@ -25,7 +25,9 @@ If any one of these facts is updated by hand, the system can split:
 - an alpha can be promoted to production even though the release tree is not the
   same tree that was tested;
 - a protected branch merge can succeed while the follow-up version commit is
-  missing.
+  missing, or a flow-internal generated `dev`/`alpha`/`release` ref update can
+  fail after publish because the automation identity was not declared in the
+  branch-protection review bypass allowance.
 
 The older ABV workflow addressed this by letting GitHub PRs drive release
 state. Buildchain keeps that choice because it makes release intent reviewable,
@@ -146,17 +148,20 @@ Buildchain then:
 This keeps the test channel self-describing. If a consumer checks out
 `v2.0-alpha`, the manifests and exact alpha tag agree.
 
-If `dev/vX/vX.Y` has already advanced while the generated alpha version-state PR
-was under review, Buildchain records `skipped-non-fast-forward` for the dev sync
-and still completes the exact and floating alpha tags for the reviewed alpha
-commit. Later dev changes must go through their own dev-to-alpha promotion
-instead of rewinding dev.
-
-If alpha finalization is resumed after the version-state PR is merged,
-Buildchain accepts the current alpha head as a merge commit that contains the
-recorded release material. An already-created exact alpha tag may point at the
-transaction release/material SHA or at the finalized alpha head; missing
-floating alpha tags are retried before the transaction becomes `complete`.
+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
+dev sync and still completes the exact and floating alpha tags for the reviewed
+alpha commit. Later dev changes must go through their own dev-to-alpha
+promotion instead of rewinding dev. The normal path is direct: after alpha
+merges, Buildchain applies the generated version-state commit to alpha and then
+fast-forwards dev to the same commit without a human version-state PR.
+
+If alpha finalization is resumed after generated version-state bookkeeping was
+partially applied, Buildchain accepts the current alpha head as the generated
+commit, or as a historical merge commit that contains the recorded release
+material. An already-created exact alpha tag may point at the transaction
+release/material SHA or at the finalized alpha head; missing floating alpha
+tags are retried before the transaction becomes `complete`.
 
 ## Release Semantics
 
@@ -186,11 +191,12 @@ The production channel and the test channel therefore intentionally diverge
 after release: production stays on the release commit, while alpha/dev continue
 at the next prerelease commit.
 
-If release finalization is resumed after the version-state PR is merged,
-Buildchain applies the same recovery rule: the current release head may be a
-merge commit that contains the recorded release material, existing exact tags
-and alpha/dev refs are accepted when they match the transaction, and missing
-floating `vX.Y` or `vX` tags are retried idempotently before completion.
+If release finalization is resumed after generated version-state bookkeeping was
+partially applied, Buildchain applies the same recovery rule: the current
+release head may be the generated commit, or a historical merge commit that
+contains the recorded release material, existing exact tags and alpha/dev refs
+are accepted when they match the transaction, and missing floating `vX.Y` or
+`vX` tags are retried idempotently before completion.
 
 ## Major Gate Semantics
 
@@ -393,12 +399,26 @@ The verify stage runs after generated version-state changes are applied locally
 and before any release refs move. If `verification-command` is passed directly
 to the action, that explicit command overrides `lifecycle.verify`.
 
-Protected release-line branches keep their normal review gate. When generated
-version state would move a protected alpha or release branch, Buildchain creates
-a version-state PR instead of bypassing branch protection. After that PR is
-reviewed, checked, and merged, the next promotion run verifies that only
-declared version-state files changed from the legally merged source parent, then
-moves the exact and floating tags.
+Protected release-line branches keep their normal human review gate. Managed
+`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured
+with one required approving review, strict GitHub Actions checks, administrator
+enforcement, conversation resolution, no force pushes, and no deletions. The
+reusable `release-candidate-promote.yml` wrapper defaults
+`branch-protection-bypass-apps` to `github-actions`, which lets the workflow's
+automation identity apply generated version-state or post-publish channel
+bookkeeping after the reviewed channel PR has merged. Direct
+`promote-buildchain-ref` callers must opt into the same controlled bypass with
+`branch-protection-bypass-apps`, `branch-protection-bypass-users`, or
+`branch-protection-bypass-teams`; the action also adds the current promotion
+token's authenticated user or app to the managed bypass allowlist. If direct
+generated bookkeeping is still rejected, Buildchain fails with a
+token/protection diagnostic instead of creating a post-publish PR. Buildchain's
+own promotion workflow reads `BUILDCHAIN_PROMOTION_BYPASS_APPS`,
+`BUILDCHAIN_PROMOTION_BYPASS_USERS`, and
+`BUILDCHAIN_PROMOTION_BYPASS_TEAMS` repository variables so the declared bypass
+identity can match the actual `BUILDCHAIN_PROMOTION_TOKEN` actor, but consumers
+do not need to duplicate that actor manually when the token identity is
+discoverable.
 
 ## What This Guarantees
 
@@ -414,6 +434,9 @@ When the loop succeeds, maintainers and consumers can rely on these facts:
 - 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;
+- flow-internal automation bypasses apply only to declared GitHub Apps, users,
+  or teams on Buildchain-managed channel branch protection, while one-review
+  protection remains enforced for humans;
 - admin users cannot make a channel promotion valid by temporarily bypassing
   branch protection.
 

package/docs/reusable-build-surface.md

@@ -510,9 +510,14 @@ calls `actions/promote-buildchain-ref` with
 `require-publish-source-lock: "true"`. The wrapper passes the created
 `publish-gate/*` ref, target SHA, and `locked=true` into the promote action, so
 floating `@v2` consumers receive publish-side source-lock drift protection by
-default. It does not call `.build.yml`, does not create a matrix, and must fail
-before publish if the RC evidence, payload set, or source-lock ref is missing or
-ambiguous.
+default. It also defaults `branch-protection-bypass-apps` to `github-actions`
+so the workflow automation can apply generated version-state and channel
+bookkeeping on protected `dev`/`alpha`/`release` branches after the reviewed
+channel PR has merged; consumers using a different promotion identity can pass
+`branch-protection-bypass-users`, `branch-protection-bypass-teams`, or a
+different app slug declaratively. It does not call `.build.yml`, does not create
+a matrix, and must fail before publish if the RC evidence, payload set, or
+source-lock ref is missing or ambiguous.
 
 ```yaml
 jobs:

package/package.json

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