@kungfu-tech/buildchain 2.14.18-alpha.3 → 2.14.18-alpha.5

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

@@ -405,16 +405,16 @@ governance semantics:
   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 the reusable build trust gate now checks the source-lock channel HEAD and
-merged same-repository PR lineage before heavy build runners start. This action
-still independently rechecks PR lineage, alpha/release tree equivalence, and
-generated version-state verification before moving channel refs and tags.
-Generated version-state direct ref updates can use a separate
-`generated-ref-update-token`; the reusable wrapper binds it to the run-scoped
-`github.token`.
+The reusable promotion workflow keeps governance reads, generated status checks,
+and generated ref updates on the run-scoped `github.token`. When branch
+protection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`
+only through `generated-pull-request-token` so the same-repository recovery PR can
+be listed or created without broadening the governance client. Protected branch
+review and check rules guard human channel merges, while the reusable build trust
+gate checks the source-lock channel HEAD and merged same-repository PR lineage
+before heavy build runners start. This action still independently rechecks PR
+lineage, alpha/release tree equivalence, and generated version-state verification
+before moving channel refs and tags.
 The reusable `release-candidate-promote.yml` wrapper defaults
 `branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion
 can complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.14.18-alpha.3",
+    "version": "2.14.18-alpha.5",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -170,7 +170,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:1f476fb9a4854b362c4b24cef89a3c7675d7d63baf3bc828d7b8ae7d2787cead",
-      "auditDigest": "sha256:a328740bbd24990af1a95e93055de54ff6261ec6c9943b53d209440c7cb4a4cc"
+      "auditDigest": "sha256:5a5cbec0b5382c34101623ed11f264797b618920d8c98c78e0d14af9f07a1f6b"
     },
     {
       "contractVersion": 1,
@@ -212,7 +212,7 @@
         "promotion reuses PR-stage release-candidate artifacts and does not run the heavy native build matrix"
       ],
       "breakingDigest": "sha256:aa30f22e3af0a89841310bdbdc900844dd95a66974db173fa140a71bbd7e82c0",
-      "auditDigest": "sha256:fc3bab430f17f990948c98b93cf1d07643982548881c230e37adac8ad9bdb662"
+      "auditDigest": "sha256:e3d7a8c05fb4564748440d363b9f97c3ad9a019f960ec2e874dc073f94056d52"
     },
     {
       "contractVersion": 1,
@@ -256,7 +256,7 @@
         "channel-aware artifact host facts are checked against the deploy plan before adapter side effects"
       ],
       "breakingDigest": "sha256:da569f90374e878948e3d5160ed9929338ce0572473ca8ee54867b0fe1aaeace",
-      "auditDigest": "sha256:3032fbbba0920b0ec2b7e1e4ba96a5a7e51c10249ff4e5bc9f0ad81b933eae45"
+      "auditDigest": "sha256:063dfe24e1ccdd95b4ffbf89a154aa71197c8bd1cb98b4705d8663917c026366"
     },
     {
       "contractVersion": 1,
@@ -327,7 +327,7 @@
         "sha256:a59f0910e6df842e7699139472e5dd69ac2fdd7f7213bf2cb346d1d622556874"
       ],
       "breakingDigest": "sha256:6147c0a8d5c36bfaa6021871574e1fc28192a3f1b8cfdae4d24ef3059ac1ebda",
-      "auditDigest": "sha256:40247c580fb55f387c0d0c9f26adb7e7f111dafe600444ec815134c080b09cff"
+      "auditDigest": "sha256:c23298988d29d6dbf99c65fd7d5567d704f012cc7a061c46a848c26814cab4b9"
     },
     {
       "contractVersion": 1,
@@ -641,7 +641,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:79677fecc366c7769100648324a597456e03e91768a5e16570a3ce3c171d8e84"
+      "auditDigest": "sha256:e4d6e0b9016dec3a0bc2425fffedf2414969345b7fabef615a6b9715dddbab27"
     },
     {
       "contractVersion": 1,
@@ -2018,7 +2018,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:f14825324a16b51c2e9ed708ebe64e1932e05b6d5e0866f83aea8439decb4a27",
-      "auditDigest": "sha256:3032fbbba0920b0ec2b7e1e4ba96a5a7e51c10249ff4e5bc9f0ad81b933eae45"
+      "auditDigest": "sha256:063dfe24e1ccdd95b4ffbf89a154aa71197c8bd1cb98b4705d8663917c026366"
     },
     {
       "contractVersion": 1,
@@ -2428,7 +2428,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:0eb318df455ef9cb737a7c2515a2411b685d34ed0bde7b5f5b173a7a42513114",
-      "auditDigest": "sha256:56a9f981034988be3d796119a5704c592bd080d61211a03eb364e93210323d9d"
+      "auditDigest": "sha256:fd939f9dcce745f3e1b8063b68715460cb8e1af6d2b813a96b37a741740122b9"
     },
     {
       "contractVersion": 1,
@@ -2928,7 +2928,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:015d8de793adbd4c539416be7d7512e18cc92097e629b0203fa06d2c183e98bd",
-      "auditDigest": "sha256:fc3bab430f17f990948c98b93cf1d07643982548881c230e37adac8ad9bdb662"
+      "auditDigest": "sha256:e3d7a8c05fb4564748440d363b9f97c3ad9a019f960ec2e874dc073f94056d52"
     },
     {
       "contractVersion": 1,
@@ -3126,5 +3126,5 @@
     }
   ],
   "compatibilityDigest": "sha256:df13c3b8066068925ce847b31002201d533034d10d342542422db3a665c10475",
-  "contractDigest": "sha256:4e538fc6bc877664f5f9786cef16ea326fd735ad5b3404ba5b25541411ed0949"
+  "contractDigest": "sha256:4524bea43ac00174e3ce2565d7787b695c2ffbb7e3d95718fec3358ac6a0fbaa"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-24T11:35:01.198Z",
-  "publishedAt": "2026-07-24T11:35:01.198Z",
+  "generatedAt": "2026-07-24T12:46:36.499Z",
+  "publishedAt": "2026-07-24T12:46:36.499Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "b5f602c1f99af9b4177dd26b5c12ffd4ad90a497",
+  "sourceRevision": "13b001a82ed1e6845b864028e0cce5b72c5d36c7",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.18-alpha.3",
+    "version": "2.14.18-alpha.5",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -206,7 +206,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/promote-buildchain-ref/README.md",
-      "digest": "sha256:2d03ceaec46ef68f116508ca5ac0f1609f59f5335e9681d258e2f090569c136a",
+      "digest": "sha256:12f86449a1f7b324d6a411b62dfd0475af68ce6e7270feaa07c221f99cf37d32",
       "headings": [
         {
           "level": 1,
@@ -224,7 +224,7 @@
           "anchor": "publish-transactions"
         }
       ],
-      "markdown": "# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as\n  `v2.0.1-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v2.0-alpha` and, when this is the highest published alpha minor, `v2-alpha`;\n- `release/v2/v2.0` creates or reuses the next exact release tag such as\n  `v2.0.0`, writes that version into package version state, points the release\n  channel branch and release tags at the release commit, then prepares a second\n  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and\n  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease\n  commit, and moves `v2-alpha` only if no higher v2 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v2/v2.0`, writes the next major production version such as\n  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`\n  at that release commit, then prepares `v3.0.1-alpha.0` for\n  `alpha/v3/v3.0`, `dev/v3/v3.0`, `v3.0-alpha`, and `v3-alpha`. The older `major-gate`\n  branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only\nwhen the next minor tag such as `v2.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n  `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v2/v2.0\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n    publish-required-artifacts-json: >-\n      [\n        {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"2.0.0\",\"digest\":\"sha256:...\"}\n      ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/<version>`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n  protection for administrators and require approving PR review plus the strict\n  `check` job from the `Verify` workflow; when GitHub withholds that\n  administration endpoint from the workflow token, the exact transaction must\n  instead prove a protected current head, same-repository merged PR,\n  independent approval, and the required successful `check` from its configured\n  GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n  provider-enforced policy when the workflow token cannot read or rewrite the\n  administrative protection document, and fails closed if the public branch\n  summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n  `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n  `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n  `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n  `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n  `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n  the release source tree must match that alpha tag tree, so release does not\n  introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n  declared `version.files` and the configured anchor manifest, and only when the\n  checked-out release material has passed `lifecycle.verify` or the explicit\n  `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n  with either the `verification-command` input or `buildchain.toml`\n  `lifecycle.verify` before any tags or channel refs move.\n\nThe promotion workflow should use `BUILDCHAIN_PROMOTION_TOKEN` for non-dry-run\npromotion. The token is the buildchain equivalent of the old ABV runner release\nauthority: protected branch review and check rules guard human channel merges,\nwhile the reusable build trust gate now checks the source-lock channel HEAD and\nmerged same-repository PR lineage before heavy build runners start. This action\nstill independently rechecks PR lineage, alpha/release tree equivalence, and\ngenerated version-state verification before moving channel refs and tags.\nGenerated version-state direct ref updates can use a separate\n`generated-ref-update-token`; the reusable wrapper binds it to the run-scoped\n`github.token`.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v2.0` and `v2`, and floating alpha\ntags are minor-line tags such as `v2.0-alpha` plus cross-minor major tags such\nas `v2-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha` and `v2-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
+      "markdown": "# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as\n  `v2.0.1-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v2.0-alpha` and, when this is the highest published alpha minor, `v2-alpha`;\n- `release/v2/v2.0` creates or reuses the next exact release tag such as\n  `v2.0.0`, writes that version into package version state, points the release\n  channel branch and release tags at the release commit, then prepares a second\n  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and\n  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease\n  commit, and moves `v2-alpha` only if no higher v2 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v2/v2.0`, writes the next major production version such as\n  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`\n  at that release commit, then prepares `v3.0.1-alpha.0` for\n  `alpha/v3/v3.0`, `dev/v3/v3.0`, `v3.0-alpha`, and `v3-alpha`. The older `major-gate`\n  branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only\nwhen the next minor tag such as `v2.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n  `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v2/v2.0\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n    publish-required-artifacts-json: >-\n      [\n        {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"2.0.0\",\"digest\":\"sha256:...\"}\n      ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/<version>`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n  protection for administrators and require approving PR review plus the strict\n  `check` job from the `Verify` workflow; when GitHub withholds that\n  administration endpoint from the workflow token, the exact transaction must\n  instead prove a protected current head, same-repository merged PR,\n  independent approval, and the required successful `check` from its configured\n  GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n  provider-enforced policy when the workflow token cannot read or rewrite the\n  administrative protection document, and fails closed if the public branch\n  summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n  `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n  `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n  `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n  `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n  `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n  the release source tree must match that alpha tag tree, so release does not\n  introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n  declared `version.files` and the configured anchor manifest, and only when the\n  checked-out release material has passed `lifecycle.verify` or the explicit\n  `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n  with either the `verification-command` input or `buildchain.toml`\n  `lifecycle.verify` before any tags or channel refs move.\n\nThe reusable promotion workflow keeps governance reads, generated status checks,\nand generated ref updates on the run-scoped `github.token`. When branch\nprotection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`\nonly through `generated-pull-request-token` so the same-repository recovery PR can\nbe listed or created without broadening the governance client. Protected branch\nreview and check rules guard human channel merges, while the reusable build trust\ngate checks the source-lock channel HEAD and merged same-repository PR lineage\nbefore heavy build runners start. This action still independently rechecks PR\nlineage, alpha/release tree equivalence, and generated version-state verification\nbefore moving channel refs and tags.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v2.0` and `v2`, and floating alpha\ntags are minor-line tags such as `v2.0-alpha` plus cross-minor major tags such\nas `v2-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha` and `v2-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
     },
     {
       "id": "action:report-buildchain-issue",
@@ -600,7 +600,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/github-governance-authority.md",
-      "digest": "sha256:3103d7982c9a30b344c603566520aeb1d5d90c1c54958d9c1c2b7ae897359da8",
+      "digest": "sha256:8484b18d5b0fe6d61d102d6b9cb9e18beac9f47ecb516d430fb5427518e2931f",
       "headings": [
         {
           "level": 1,
@@ -633,7 +633,7 @@
           "anchor": "mutation-and-rollback-boundary"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: github-governance-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-24\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-24\n  limits: Live GitHub state and account recovery remain provider-controlled and must be re-audited.\n---\n\n# GitHub Governance Authority\n\nBuildchain treats GitHub governance as an independently verified, fail-closed\nauthority boundary. A green CI run, a CODEOWNERS file, an API success response,\nor an administrator's assertion is not sufficient by itself. The verifier\ncombines the exact CODEOWNERS bytes from the target base branch, classic branch\nprotection, every applicable repository or organization ruleset, account role\nclasses, plan capability, required checks, and provider-read completeness into\none short-lived immutable receipt.\n\nThe machine contract is\n`@kungfu-tech/buildchain/github-governance-authority`. Its policy root covers\nthe managed-zone repository and target-ref admission rules, the exact\nrequired-check context/App bindings and strict-update semantics for every\npublic authoritative target, the dual-account authority split, protected\nverifier paths, native review requirements, break-glass constraints, and the\nexplicit trust boundary.\n\n## Trust boundary and non-claims\n\nThe trusted computing base contains GitHub service integrity, retained\norganization-owner recovery custody, the `kungfu-origin` review/governance\nidentity, the exact Buildchain verifier, and official publication identities.\nThe protocol does not claim resistance to compromise of GitHub itself,\ncompromise of all retained owner and recovery anchors, or malicious control of\nall independent trust anchors. A governance receipt grants no GitHub\npermission and is not a bearer credential.\n\n`dongkeren` is the development and pull-request author identity.\n`kungfu-origin` is the independent Code Owner and governance identity. A\nqualifying receipt requires the development identity to be active without an\nadministrator or maintainer role and requires the review identity to retain the\nadmitted governance role. Account recovery and retained root custody remain\noutside normal contributor and workflow paths.\n\n## Effective policy\n\nThe verifier evaluates native provider layers together. Every authoritative\ntarget must require:\n\n- a pull request, at least one independent Code Owner approval, and a fresh\n  approval after the latest reviewable push;\n- administrator enforcement, resolved review conversations, and a non-empty\n  required-check set whose exact contexts, GitHub App producer identities, and\n  strict-update setting match the versioned target policy;\n- no unapproved bypass actor, force push, or protected-ref deletion. Managed\n  dev/alpha/release ref bookkeeping may admit only the exact GitHub Actions App\n  identity versioned for that target; user and team bypass actors remain\n  non-qualifying;\n- exact last-match ownership of CODEOWNERS and the governance descriptor,\n  collector, rollout planner, and scheduled audit workflow;\n- complete readable GitHub API evidence. Missing, forbidden, ambiguous, or\n  malformed provider state is non-qualifying.\n\nRepository and organization rulesets are additive to classic branch\nprotection. Inspecting only one layer is insufficient because an applicable\nbypass or weaker update path in another layer can invalidate the effective\npolicy.\n\n## Repository and plan admission\n\nThe 2026-07-24 baseline contains 16 managed repositories: 13 public and three\nprivate. Public repository names are versioned in the descriptor. Private\nrepository names are never emitted in public evidence; their identities are\nrepresented by stable roots derived from the GitHub provider repository ID,\nindependent of the governance policy root. This prevents a policy revision from\nchanging repository identity or creating a circular admission dependency. A\nnewly discovered repository or target ref is non-authoritative until explicitly\nadmitted.\n\nThe descriptor also versions every active public merge target. The full audit\nevaluates one receipt per authoritative target rather than assuming the default\nbranch represents dev, alpha, release, or major publish-gate branches. The live\ndefault branch is always included even if it drifts outside the registry, in\nwhich case it is non-qualifying. Retained historical channels and generated\nper-release publish-gate refs are not silently deleted or promoted to current\nauthority; they require an explicit registry revision before they can qualify.\n\nFor an admitted private repository, the active target set is the current\ndefault branch plus existing alpha/release siblings on the same version line.\nIts required-check bindings remain non-qualifying until their sanitized binding\nroots are sealed into the private identity entry after supported native\nprotection exists.\n\nPublic repositories can qualify on supported Free, Team, or Enterprise\nenforcement. Private repositories and organization-wide rules require Team or\nEnterprise capability. On an unsupported plan they remain explicitly\n`non-authoritative-plan-capability-required` and publication-ineligible. The\nverifier does not replace missing native enforcement with CI or documentation,\nand the implementation never makes a private repository public as a\nworkaround.\n\n## Read-only audit\n\nRun the organization audit without mutation:\n\n```bash\nbuildchain audit github-governance \\\n  --organization kungfu-systems \\\n  --output github-governance.json \\\n  --json\n```\n\nLimit a canary to one repository:\n\n```bash\nbuildchain audit github-governance \\\n  --repository kungfu-systems/buildchain \\\n  --target-ref dev/v2/v2.14 \\\n  --require-qualifying \\\n  --json\n```\n\nProtected merge and publication consumers verify the receipt against the exact\nrepository, target base ref, policy root, freshness window, and exact\nBuildchain verifier source revision. Non-dry-run publication does not trust a\ncaller-supplied JSON hash: it mints a bounded token for the dedicated read-only\ngovernance auditor GitHub App, recollects live provider state with the exact\nBuildchain runtime, requires the resulting single-repository/single-target\naudit to qualify, and consumes that independently generated receipt. Missing\nApp configuration or unreadable provider state denies publication before\nprovider mutation. The publication authority workflow is itself an explicit\nCode Owner path.\n\nThe output is sanitized. Public repositories retain their public identity.\nPrivate repositories expose only an identity root, visibility class, target\nref, sanitized required-check bindings and fact roots, and a qualifying or\nnon-qualifying decision. Tokens, cookies, recovery material, private\nCODEOWNERS bytes, raw permission payloads, and credential-bearing URLs are\nnever included.\n\n## Mutation and rollback boundary\n\nLive role, ruleset, branch-protection, Actions, Environment, or repository\nchanges are separate from audit. Every mutation starts from a read-only\ninventory and a frozen rollback snapshot. A rollout plan binds both roots and\nlists the exact API operation, impact, expected observation, and inverse\noperation. Apply must stop on the first unexplained drift and must perform a\npost-change read-back before continuing to the next bounded canary.\n\nPlan one exact branch without mutation:\n\n```bash\nbuildchain github-governance plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.14 \\\n  --required-check check \\\n  --required-check-app-id check=15368 \\\n  --required-approvals 1 \\\n  --snapshot-output rollback.json \\\n  --plan-output rollout.json\n```\n\nAn already protected check preserves its observed GitHub App binding. Every new\nrequired check must declare `--required-check-app-id <context>=<app-id>`;\ncontext-only replacement is rejected because it would broaden which producer\ncan satisfy the gate.\n\nClassic branch-protection bypass allowances and ruleset bypass actors are both\npart of the effective policy. Reconciliation writes explicit empty user, team,\nand App bypass lists and verifies those lists after apply; omitting the provider\nfield is not treated as removal because GitHub may preserve the prior value.\n\nThe plan prints a `planRoot`. Apply requires that exact root and stops if live\nprotection no longer matches the frozen inventory:\n\n```bash\nbuildchain github-governance apply \\\n  --plan-json rollout.json \\\n  --confirm-plan-root sha256:...\n```\n\nRollback is separately explicit and root-bound:\n\n```bash\nbuildchain github-governance rollback \\\n  --plan-json rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, classic branch protection can also be compiled\ndirectly from the authority descriptor. This mode preserves both App-bound\nchecks and intentionally unbound check contexts such as Kungfu alpha's\n`build`, rather than guessing a provider App identity.\n\n```bash\nbuildchain github-governance protection-policy-plan \\\n  --repository kungfu-systems/kungfu \\\n  --branch alpha/v4/v4.0 \\\n  --snapshot-output protection-rollback.json \\\n  --plan-output protection-rollout.json\n\nbuildchain github-governance protection-policy-apply \\\n  --plan-json protection-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance protection-policy-rollback \\\n  --plan-json protection-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, repository ruleset reconciliation compiles the\ntarget descriptor into the provider body. It replaces bypass actors with the\nexact provider-admitted desired set, requires fresh Code Owner approval and\nresolved review threads, and binds required checks plus strict-update semantics\nto the target policy. Newly synthesized managed rules include GitHub's explicit\ncanonical defaults so the frozen expected root matches provider read-back.\nRepository rulesets default to no bypass actors. The\ndescriptor's target-bound GitHub Actions allowance is an upper bound on\neffective provider state, not a requirement to add that actor to every\nprotection layer; when needed, the built-in App allowance is expressed by\nclassic branch protection. The target condition must contain exactly one\nbranch; unrelated rules and conditions are preserved in place.\n\n```bash\nbuildchain github-governance ruleset-policy-plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch alpha/v2/v2.14 \\\n  --ruleset-id 19518955 \\\n  --snapshot-output ruleset-rollback.json \\\n  --plan-output ruleset-rollout.json\n\nbuildchain github-governance ruleset-policy-apply \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance ruleset-policy-rollback \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nThe narrower `ruleset-plan` mode changes only `bypass_actors`; it remains\navailable for a bypass-only canary, but it cannot prove that an effective\nruleset matches the target descriptor. Both modes require the frozen ruleset\nsnapshot root for rollback.\n\nPaid-plan purchase, billing, legal/account-owner decisions, and any operation\nthat could remove the last recoverable owner remain external human gates.\nBreak-glass is disabled by default and, if ever admitted, must be separately\nauthenticated, reason-bound, time-bounded, independently receipted, and\nfollowed by mandatory restoration and root comparison."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: github-governance-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-24\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-24\n  limits: Live GitHub state and account recovery remain provider-controlled and must be re-audited.\n---\n\n# GitHub Governance Authority\n\nBuildchain treats GitHub governance as an independently verified, fail-closed\nauthority boundary. A green CI run, a CODEOWNERS file, an API success response,\nor an administrator's assertion is not sufficient by itself. The verifier\ncombines the exact CODEOWNERS bytes from the target base branch, classic branch\nprotection, every applicable repository or organization ruleset, account role\nclasses, plan capability, required checks, and provider-read completeness into\none short-lived immutable receipt.\n\nThe machine contract is\n`@kungfu-tech/buildchain/github-governance-authority`. Its policy root covers\nthe managed-zone repository and target-ref admission rules, the exact\nrequired-check context/App bindings and strict-update semantics for every\npublic authoritative target, the dual-account authority split, protected\nverifier paths, native review requirements, break-glass constraints, and the\nexplicit trust boundary.\n\n## Trust boundary and non-claims\n\nThe trusted computing base contains GitHub service integrity, retained\norganization-owner recovery custody, the `kungfu-origin` review/governance\nidentity, the exact Buildchain verifier, and official publication identities.\nThe protocol does not claim resistance to compromise of GitHub itself,\ncompromise of all retained owner and recovery anchors, or malicious control of\nall independent trust anchors. A governance receipt grants no GitHub\npermission and is not a bearer credential.\n\n`dongkeren` is the development and pull-request author identity.\n`kungfu-origin` is the independent Code Owner and governance identity. A\nqualifying receipt requires the development identity to be active without an\nadministrator or maintainer role and requires the review identity to retain the\nadmitted governance role. Account recovery and retained root custody remain\noutside normal contributor and workflow paths.\n\n## Effective policy\n\nThe verifier evaluates native provider layers together. Every authoritative\ntarget must require:\n\n- a pull request, at least one independent Code Owner approval, and a fresh\n  approval after the latest reviewable push;\n- administrator enforcement, resolved review conversations, and a non-empty\n  required-check set whose exact contexts, GitHub App producer identities, and\n  strict-update setting match the versioned target policy;\n- no unapproved bypass actor, force push, or protected-ref deletion. Managed\n  dev/alpha/release ref bookkeeping may admit only the exact GitHub Actions App\n  identity versioned for that target; user and team bypass actors remain\n  non-qualifying;\n- exact last-match ownership of CODEOWNERS and the governance descriptor,\n  collector, rollout planner, and scheduled audit workflow;\n- complete readable GitHub API evidence. Missing, forbidden, ambiguous, or\n  malformed provider state is non-qualifying.\n\nRepository and organization rulesets are additive to classic branch\nprotection. Inspecting only one layer is insufficient because an applicable\nbypass or weaker update path in another layer can invalidate the effective\npolicy.\n\n## Repository and plan admission\n\nThe 2026-07-24 baseline contains 16 managed repositories: 13 public and three\nprivate. Public repository names are versioned in the descriptor. Private\nrepository names are never emitted in public evidence; their identities are\nrepresented by stable roots derived from the GitHub provider repository ID,\nindependent of the governance policy root. This prevents a policy revision from\nchanging repository identity or creating a circular admission dependency. A\nnewly discovered repository or target ref is non-authoritative until explicitly\nadmitted.\n\nThe descriptor also versions every active public merge target. The full audit\nevaluates one receipt per authoritative target rather than assuming the default\nbranch represents dev, alpha, release, or major publish-gate branches. The live\ndefault branch is always included even if it drifts outside the registry, in\nwhich case it is non-qualifying. Retained historical channels and generated\nper-release publish-gate refs are not silently deleted or promoted to current\nauthority; they require an explicit registry revision before they can qualify.\n\nFor an admitted private repository, the active target set is the current\ndefault branch plus existing alpha/release siblings on the same version line.\nIts required-check bindings remain non-qualifying until their sanitized binding\nroots are sealed into the private identity entry after supported native\nprotection exists.\n\nPublic repositories can qualify on supported Free, Team, or Enterprise\nenforcement. Private repositories and organization-wide rules require Team or\nEnterprise capability. On an unsupported plan they remain explicitly\n`non-authoritative-plan-capability-required` and publication-ineligible. The\nverifier does not replace missing native enforcement with CI or documentation,\nand the implementation never makes a private repository public as a\nworkaround.\n\n## Read-only audit\n\nRun the organization audit without mutation:\n\n```bash\nbuildchain audit github-governance \\\n  --organization kungfu-systems \\\n  --output github-governance.json \\\n  --json\n```\n\nLimit a canary to one repository:\n\n```bash\nbuildchain audit github-governance \\\n  --repository kungfu-systems/buildchain \\\n  --target-ref dev/v2/v2.14 \\\n  --require-qualifying \\\n  --json\n```\n\nProtected merge and publication consumers verify the receipt against the exact\nrepository, target base ref, policy root, freshness window, and exact\nBuildchain verifier source revision. Non-dry-run publication does not trust a\ncaller-supplied JSON hash: it mints a bounded token for the dedicated read-only\ngovernance auditor GitHub App, recollects live provider state with the exact\nBuildchain runtime, requires the resulting single-repository/single-target\naudit to qualify, and consumes that independently generated receipt. Missing\nApp configuration or unreadable provider state denies publication before\nprovider mutation. The publication authority workflow is itself an explicit\nCode Owner path.\n\nThe publication authority job and every reusable-workflow caller grant the\nbuilt-in `GITHUB_TOKEN` only `actions: read`, `checks: read`, `contents: read`,\nand `pull-requests: read`. The dedicated auditor App independently recollects\nthe organization-wide governance receipt, while these job-scoped permissions\nallow the exact publication transaction audit to resolve required check runs\nand merged pull-request review lineage. Omitting either read permission makes\nthe transaction evidence incomplete and therefore non-qualifying.\n\nThe output is sanitized. Public repositories retain their public identity.\nPrivate repositories expose only an identity root, visibility class, target\nref, sanitized required-check bindings and fact roots, and a qualifying or\nnon-qualifying decision. Tokens, cookies, recovery material, private\nCODEOWNERS bytes, raw permission payloads, and credential-bearing URLs are\nnever included.\n\n## Mutation and rollback boundary\n\nLive role, ruleset, branch-protection, Actions, Environment, or repository\nchanges are separate from audit. Every mutation starts from a read-only\ninventory and a frozen rollback snapshot. A rollout plan binds both roots and\nlists the exact API operation, impact, expected observation, and inverse\noperation. Apply must stop on the first unexplained drift and must perform a\npost-change read-back before continuing to the next bounded canary.\n\nPlan one exact branch without mutation:\n\n```bash\nbuildchain github-governance plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.14 \\\n  --required-check check \\\n  --required-check-app-id check=15368 \\\n  --required-approvals 1 \\\n  --snapshot-output rollback.json \\\n  --plan-output rollout.json\n```\n\nAn already protected check preserves its observed GitHub App binding. Every new\nrequired check must declare `--required-check-app-id <context>=<app-id>`;\ncontext-only replacement is rejected because it would broaden which producer\ncan satisfy the gate.\n\nClassic branch-protection bypass allowances and ruleset bypass actors are both\npart of the effective policy. Reconciliation writes explicit empty user, team,\nand App bypass lists and verifies those lists after apply; omitting the provider\nfield is not treated as removal because GitHub may preserve the prior value.\n\nThe plan prints a `planRoot`. Apply requires that exact root and stops if live\nprotection no longer matches the frozen inventory:\n\n```bash\nbuildchain github-governance apply \\\n  --plan-json rollout.json \\\n  --confirm-plan-root sha256:...\n```\n\nRollback is separately explicit and root-bound:\n\n```bash\nbuildchain github-governance rollback \\\n  --plan-json rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, classic branch protection can also be compiled\ndirectly from the authority descriptor. This mode preserves both App-bound\nchecks and intentionally unbound check contexts such as Kungfu alpha's\n`build`, rather than guessing a provider App identity.\n\n```bash\nbuildchain github-governance protection-policy-plan \\\n  --repository kungfu-systems/kungfu \\\n  --branch alpha/v4/v4.0 \\\n  --snapshot-output protection-rollback.json \\\n  --plan-output protection-rollout.json\n\nbuildchain github-governance protection-policy-apply \\\n  --plan-json protection-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance protection-policy-rollback \\\n  --plan-json protection-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, repository ruleset reconciliation compiles the\ntarget descriptor into the provider body. It replaces bypass actors with the\nexact provider-admitted desired set, requires fresh Code Owner approval and\nresolved review threads, and binds required checks plus strict-update semantics\nto the target policy. Newly synthesized managed rules include GitHub's explicit\ncanonical defaults so the frozen expected root matches provider read-back.\nRepository rulesets default to no bypass actors. The\ndescriptor's target-bound GitHub Actions allowance is an upper bound on\neffective provider state, not a requirement to add that actor to every\nprotection layer; when needed, the built-in App allowance is expressed by\nclassic branch protection. The target condition must contain exactly one\nbranch; unrelated rules and conditions are preserved in place.\n\n```bash\nbuildchain github-governance ruleset-policy-plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch alpha/v2/v2.14 \\\n  --ruleset-id 19518955 \\\n  --snapshot-output ruleset-rollback.json \\\n  --plan-output ruleset-rollout.json\n\nbuildchain github-governance ruleset-policy-apply \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance ruleset-policy-rollback \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nThe narrower `ruleset-plan` mode changes only `bypass_actors`; it remains\navailable for a bypass-only canary, but it cannot prove that an effective\nruleset matches the target descriptor. Both modes require the frozen ruleset\nsnapshot root for rollback.\n\nPaid-plan purchase, billing, legal/account-owner decisions, and any operation\nthat could remove the last recoverable owner remain external human gates.\nBreak-glass is disabled by default and, if ever admitted, must be separately\nauthenticated, reason-bound, time-bounded, independently receipted, and\nfollowed by mandatory restoration and root comparison."
     },
     {
       "id": "manual:homebrew",
@@ -2706,7 +2706,7 @@
       "path": "docs/github-governance-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:3103d7982c9a30b344c603566520aeb1d5d90c1c54958d9c1c2b7ae897359da8"
+      "digest": "sha256:8484b18d5b0fe6d61d102d6b9cb9e18beac9f47ecb516d430fb5427518e2931f"
     },
     {
       "id": "release-candidate",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "f890bdedac11fc0da04ecb93a049c58be037fb186b6031a5cc69e5efe444c372",
+    "sha256": "9630ecd8a84c94ae0782aa7fbd22caeb027cca9f9fa40d2c3fac6f5b9ae1735e",
     "summary": {
       "cliCommandCount": 87,
       "workflowCount": 52,
@@ -228,7 +228,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "f890bdedac11fc0da04ecb93a049c58be037fb186b6031a5cc69e5efe444c372",
+      "sha256": "9630ecd8a84c94ae0782aa7fbd22caeb027cca9f9fa40d2c3fac6f5b9ae1735e",
       "summary": {
         "cliCommandCount": 87,
         "workflowCount": 52,
@@ -4203,7 +4203,7 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true,
-          "inputCount": 63,
+          "inputCount": 64,
           "inputs": [
             "allow-repository",
             "branch-protection-bypass-apps",
@@ -4211,6 +4211,7 @@
             "branch-protection-bypass-users",
             "dry-run",
             "expected-publication-version",
+            "generated-pull-request-token",
             "generated-ref-update-token",
             "generated-status-check-token",
             "github-release",

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.18-alpha.3",
+    "version": "2.14.18-alpha.5",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/manual-registry.json

@@ -79,7 +79,7 @@
       "title": "GitHub governance authority",
       "path": "docs/github-governance-authority.md",
       "plane": "verify",
-      "digest": "sha256:3103d7982c9a30b344c603566520aeb1d5d90c1c54958d9c1c2b7ae897359da8",
+      "digest": "sha256:8484b18d5b0fe6d61d102d6b9cb9e18beac9f47ecb516d430fb5427518e2931f",
       "capabilityGroup": "governance-versioning",
       "audience": [
         "maintainer",

package/dist/site/page-registry.json

@@ -140,7 +140,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/promote-buildchain-ref/README.md",
-      "digest": "sha256:2d03ceaec46ef68f116508ca5ac0f1609f59f5335e9681d258e2f090569c136a",
+      "digest": "sha256:12f86449a1f7b324d6a411b62dfd0475af68ce6e7270feaa07c221f99cf37d32",
       "headings": [
         {
           "level": 1,
@@ -158,7 +158,7 @@
           "anchor": "publish-transactions"
         }
       ],
-      "markdown": "# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as\n  `v2.0.1-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v2.0-alpha` and, when this is the highest published alpha minor, `v2-alpha`;\n- `release/v2/v2.0` creates or reuses the next exact release tag such as\n  `v2.0.0`, writes that version into package version state, points the release\n  channel branch and release tags at the release commit, then prepares a second\n  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and\n  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease\n  commit, and moves `v2-alpha` only if no higher v2 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v2/v2.0`, writes the next major production version such as\n  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`\n  at that release commit, then prepares `v3.0.1-alpha.0` for\n  `alpha/v3/v3.0`, `dev/v3/v3.0`, `v3.0-alpha`, and `v3-alpha`. The older `major-gate`\n  branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only\nwhen the next minor tag such as `v2.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n  `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v2/v2.0\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n    publish-required-artifacts-json: >-\n      [\n        {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"2.0.0\",\"digest\":\"sha256:...\"}\n      ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/<version>`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n  protection for administrators and require approving PR review plus the strict\n  `check` job from the `Verify` workflow; when GitHub withholds that\n  administration endpoint from the workflow token, the exact transaction must\n  instead prove a protected current head, same-repository merged PR,\n  independent approval, and the required successful `check` from its configured\n  GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n  provider-enforced policy when the workflow token cannot read or rewrite the\n  administrative protection document, and fails closed if the public branch\n  summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n  `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n  `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n  `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n  `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n  `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n  the release source tree must match that alpha tag tree, so release does not\n  introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n  declared `version.files` and the configured anchor manifest, and only when the\n  checked-out release material has passed `lifecycle.verify` or the explicit\n  `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n  with either the `verification-command` input or `buildchain.toml`\n  `lifecycle.verify` before any tags or channel refs move.\n\nThe promotion workflow should use `BUILDCHAIN_PROMOTION_TOKEN` for non-dry-run\npromotion. The token is the buildchain equivalent of the old ABV runner release\nauthority: protected branch review and check rules guard human channel merges,\nwhile the reusable build trust gate now checks the source-lock channel HEAD and\nmerged same-repository PR lineage before heavy build runners start. This action\nstill independently rechecks PR lineage, alpha/release tree equivalence, and\ngenerated version-state verification before moving channel refs and tags.\nGenerated version-state direct ref updates can use a separate\n`generated-ref-update-token`; the reusable wrapper binds it to the run-scoped\n`github.token`.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v2.0` and `v2`, and floating alpha\ntags are minor-line tags such as `v2.0-alpha` plus cross-minor major tags such\nas `v2-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha` and `v2-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
+      "markdown": "# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as\n  `v2.0.1-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v2.0-alpha` and, when this is the highest published alpha minor, `v2-alpha`;\n- `release/v2/v2.0` creates or reuses the next exact release tag such as\n  `v2.0.0`, writes that version into package version state, points the release\n  channel branch and release tags at the release commit, then prepares a second\n  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and\n  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease\n  commit, and moves `v2-alpha` only if no higher v2 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v2/v2.0`, writes the next major production version such as\n  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`\n  at that release commit, then prepares `v3.0.1-alpha.0` for\n  `alpha/v3/v3.0`, `dev/v3/v3.0`, `v3.0-alpha`, and `v3-alpha`. The older `major-gate`\n  branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only\nwhen the next minor tag such as `v2.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n  `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v2/v2.0\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n    publish-required-artifacts-json: >-\n      [\n        {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"2.0.0\",\"digest\":\"sha256:...\"}\n      ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/<version>`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n  protection for administrators and require approving PR review plus the strict\n  `check` job from the `Verify` workflow; when GitHub withholds that\n  administration endpoint from the workflow token, the exact transaction must\n  instead prove a protected current head, same-repository merged PR,\n  independent approval, and the required successful `check` from its configured\n  GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n  provider-enforced policy when the workflow token cannot read or rewrite the\n  administrative protection document, and fails closed if the public branch\n  summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n  `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n  `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n  `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n  `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n  `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n  the release source tree must match that alpha tag tree, so release does not\n  introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n  declared `version.files` and the configured anchor manifest, and only when the\n  checked-out release material has passed `lifecycle.verify` or the explicit\n  `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n  with either the `verification-command` input or `buildchain.toml`\n  `lifecycle.verify` before any tags or channel refs move.\n\nThe reusable promotion workflow keeps governance reads, generated status checks,\nand generated ref updates on the run-scoped `github.token`. When branch\nprotection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`\nonly through `generated-pull-request-token` so the same-repository recovery PR can\nbe listed or created without broadening the governance client. Protected branch\nreview and check rules guard human channel merges, while the reusable build trust\ngate checks the source-lock channel HEAD and merged same-repository PR lineage\nbefore heavy build runners start. This action still independently rechecks PR\nlineage, alpha/release tree equivalence, and generated version-state verification\nbefore moving channel refs and tags.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v2.0` and `v2`, and floating alpha\ntags are minor-line tags such as `v2.0-alpha` plus cross-minor major tags such\nas `v2-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha` and `v2-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
     },
     {
       "id": "action:report-buildchain-issue",
@@ -534,7 +534,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/github-governance-authority.md",
-      "digest": "sha256:3103d7982c9a30b344c603566520aeb1d5d90c1c54958d9c1c2b7ae897359da8",
+      "digest": "sha256:8484b18d5b0fe6d61d102d6b9cb9e18beac9f47ecb516d430fb5427518e2931f",
       "headings": [
         {
           "level": 1,
@@ -567,7 +567,7 @@
           "anchor": "mutation-and-rollback-boundary"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: github-governance-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-24\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-24\n  limits: Live GitHub state and account recovery remain provider-controlled and must be re-audited.\n---\n\n# GitHub Governance Authority\n\nBuildchain treats GitHub governance as an independently verified, fail-closed\nauthority boundary. A green CI run, a CODEOWNERS file, an API success response,\nor an administrator's assertion is not sufficient by itself. The verifier\ncombines the exact CODEOWNERS bytes from the target base branch, classic branch\nprotection, every applicable repository or organization ruleset, account role\nclasses, plan capability, required checks, and provider-read completeness into\none short-lived immutable receipt.\n\nThe machine contract is\n`@kungfu-tech/buildchain/github-governance-authority`. Its policy root covers\nthe managed-zone repository and target-ref admission rules, the exact\nrequired-check context/App bindings and strict-update semantics for every\npublic authoritative target, the dual-account authority split, protected\nverifier paths, native review requirements, break-glass constraints, and the\nexplicit trust boundary.\n\n## Trust boundary and non-claims\n\nThe trusted computing base contains GitHub service integrity, retained\norganization-owner recovery custody, the `kungfu-origin` review/governance\nidentity, the exact Buildchain verifier, and official publication identities.\nThe protocol does not claim resistance to compromise of GitHub itself,\ncompromise of all retained owner and recovery anchors, or malicious control of\nall independent trust anchors. A governance receipt grants no GitHub\npermission and is not a bearer credential.\n\n`dongkeren` is the development and pull-request author identity.\n`kungfu-origin` is the independent Code Owner and governance identity. A\nqualifying receipt requires the development identity to be active without an\nadministrator or maintainer role and requires the review identity to retain the\nadmitted governance role. Account recovery and retained root custody remain\noutside normal contributor and workflow paths.\n\n## Effective policy\n\nThe verifier evaluates native provider layers together. Every authoritative\ntarget must require:\n\n- a pull request, at least one independent Code Owner approval, and a fresh\n  approval after the latest reviewable push;\n- administrator enforcement, resolved review conversations, and a non-empty\n  required-check set whose exact contexts, GitHub App producer identities, and\n  strict-update setting match the versioned target policy;\n- no unapproved bypass actor, force push, or protected-ref deletion. Managed\n  dev/alpha/release ref bookkeeping may admit only the exact GitHub Actions App\n  identity versioned for that target; user and team bypass actors remain\n  non-qualifying;\n- exact last-match ownership of CODEOWNERS and the governance descriptor,\n  collector, rollout planner, and scheduled audit workflow;\n- complete readable GitHub API evidence. Missing, forbidden, ambiguous, or\n  malformed provider state is non-qualifying.\n\nRepository and organization rulesets are additive to classic branch\nprotection. Inspecting only one layer is insufficient because an applicable\nbypass or weaker update path in another layer can invalidate the effective\npolicy.\n\n## Repository and plan admission\n\nThe 2026-07-24 baseline contains 16 managed repositories: 13 public and three\nprivate. Public repository names are versioned in the descriptor. Private\nrepository names are never emitted in public evidence; their identities are\nrepresented by stable roots derived from the GitHub provider repository ID,\nindependent of the governance policy root. This prevents a policy revision from\nchanging repository identity or creating a circular admission dependency. A\nnewly discovered repository or target ref is non-authoritative until explicitly\nadmitted.\n\nThe descriptor also versions every active public merge target. The full audit\nevaluates one receipt per authoritative target rather than assuming the default\nbranch represents dev, alpha, release, or major publish-gate branches. The live\ndefault branch is always included even if it drifts outside the registry, in\nwhich case it is non-qualifying. Retained historical channels and generated\nper-release publish-gate refs are not silently deleted or promoted to current\nauthority; they require an explicit registry revision before they can qualify.\n\nFor an admitted private repository, the active target set is the current\ndefault branch plus existing alpha/release siblings on the same version line.\nIts required-check bindings remain non-qualifying until their sanitized binding\nroots are sealed into the private identity entry after supported native\nprotection exists.\n\nPublic repositories can qualify on supported Free, Team, or Enterprise\nenforcement. Private repositories and organization-wide rules require Team or\nEnterprise capability. On an unsupported plan they remain explicitly\n`non-authoritative-plan-capability-required` and publication-ineligible. The\nverifier does not replace missing native enforcement with CI or documentation,\nand the implementation never makes a private repository public as a\nworkaround.\n\n## Read-only audit\n\nRun the organization audit without mutation:\n\n```bash\nbuildchain audit github-governance \\\n  --organization kungfu-systems \\\n  --output github-governance.json \\\n  --json\n```\n\nLimit a canary to one repository:\n\n```bash\nbuildchain audit github-governance \\\n  --repository kungfu-systems/buildchain \\\n  --target-ref dev/v2/v2.14 \\\n  --require-qualifying \\\n  --json\n```\n\nProtected merge and publication consumers verify the receipt against the exact\nrepository, target base ref, policy root, freshness window, and exact\nBuildchain verifier source revision. Non-dry-run publication does not trust a\ncaller-supplied JSON hash: it mints a bounded token for the dedicated read-only\ngovernance auditor GitHub App, recollects live provider state with the exact\nBuildchain runtime, requires the resulting single-repository/single-target\naudit to qualify, and consumes that independently generated receipt. Missing\nApp configuration or unreadable provider state denies publication before\nprovider mutation. The publication authority workflow is itself an explicit\nCode Owner path.\n\nThe output is sanitized. Public repositories retain their public identity.\nPrivate repositories expose only an identity root, visibility class, target\nref, sanitized required-check bindings and fact roots, and a qualifying or\nnon-qualifying decision. Tokens, cookies, recovery material, private\nCODEOWNERS bytes, raw permission payloads, and credential-bearing URLs are\nnever included.\n\n## Mutation and rollback boundary\n\nLive role, ruleset, branch-protection, Actions, Environment, or repository\nchanges are separate from audit. Every mutation starts from a read-only\ninventory and a frozen rollback snapshot. A rollout plan binds both roots and\nlists the exact API operation, impact, expected observation, and inverse\noperation. Apply must stop on the first unexplained drift and must perform a\npost-change read-back before continuing to the next bounded canary.\n\nPlan one exact branch without mutation:\n\n```bash\nbuildchain github-governance plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.14 \\\n  --required-check check \\\n  --required-check-app-id check=15368 \\\n  --required-approvals 1 \\\n  --snapshot-output rollback.json \\\n  --plan-output rollout.json\n```\n\nAn already protected check preserves its observed GitHub App binding. Every new\nrequired check must declare `--required-check-app-id <context>=<app-id>`;\ncontext-only replacement is rejected because it would broaden which producer\ncan satisfy the gate.\n\nClassic branch-protection bypass allowances and ruleset bypass actors are both\npart of the effective policy. Reconciliation writes explicit empty user, team,\nand App bypass lists and verifies those lists after apply; omitting the provider\nfield is not treated as removal because GitHub may preserve the prior value.\n\nThe plan prints a `planRoot`. Apply requires that exact root and stops if live\nprotection no longer matches the frozen inventory:\n\n```bash\nbuildchain github-governance apply \\\n  --plan-json rollout.json \\\n  --confirm-plan-root sha256:...\n```\n\nRollback is separately explicit and root-bound:\n\n```bash\nbuildchain github-governance rollback \\\n  --plan-json rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, classic branch protection can also be compiled\ndirectly from the authority descriptor. This mode preserves both App-bound\nchecks and intentionally unbound check contexts such as Kungfu alpha's\n`build`, rather than guessing a provider App identity.\n\n```bash\nbuildchain github-governance protection-policy-plan \\\n  --repository kungfu-systems/kungfu \\\n  --branch alpha/v4/v4.0 \\\n  --snapshot-output protection-rollback.json \\\n  --plan-output protection-rollout.json\n\nbuildchain github-governance protection-policy-apply \\\n  --plan-json protection-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance protection-policy-rollback \\\n  --plan-json protection-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, repository ruleset reconciliation compiles the\ntarget descriptor into the provider body. It replaces bypass actors with the\nexact provider-admitted desired set, requires fresh Code Owner approval and\nresolved review threads, and binds required checks plus strict-update semantics\nto the target policy. Newly synthesized managed rules include GitHub's explicit\ncanonical defaults so the frozen expected root matches provider read-back.\nRepository rulesets default to no bypass actors. The\ndescriptor's target-bound GitHub Actions allowance is an upper bound on\neffective provider state, not a requirement to add that actor to every\nprotection layer; when needed, the built-in App allowance is expressed by\nclassic branch protection. The target condition must contain exactly one\nbranch; unrelated rules and conditions are preserved in place.\n\n```bash\nbuildchain github-governance ruleset-policy-plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch alpha/v2/v2.14 \\\n  --ruleset-id 19518955 \\\n  --snapshot-output ruleset-rollback.json \\\n  --plan-output ruleset-rollout.json\n\nbuildchain github-governance ruleset-policy-apply \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance ruleset-policy-rollback \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nThe narrower `ruleset-plan` mode changes only `bypass_actors`; it remains\navailable for a bypass-only canary, but it cannot prove that an effective\nruleset matches the target descriptor. Both modes require the frozen ruleset\nsnapshot root for rollback.\n\nPaid-plan purchase, billing, legal/account-owner decisions, and any operation\nthat could remove the last recoverable owner remain external human gates.\nBreak-glass is disabled by default and, if ever admitted, must be separately\nauthenticated, reason-bound, time-bounded, independently receipted, and\nfollowed by mandatory restoration and root comparison."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: github-governance-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-24\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-24\n  limits: Live GitHub state and account recovery remain provider-controlled and must be re-audited.\n---\n\n# GitHub Governance Authority\n\nBuildchain treats GitHub governance as an independently verified, fail-closed\nauthority boundary. A green CI run, a CODEOWNERS file, an API success response,\nor an administrator's assertion is not sufficient by itself. The verifier\ncombines the exact CODEOWNERS bytes from the target base branch, classic branch\nprotection, every applicable repository or organization ruleset, account role\nclasses, plan capability, required checks, and provider-read completeness into\none short-lived immutable receipt.\n\nThe machine contract is\n`@kungfu-tech/buildchain/github-governance-authority`. Its policy root covers\nthe managed-zone repository and target-ref admission rules, the exact\nrequired-check context/App bindings and strict-update semantics for every\npublic authoritative target, the dual-account authority split, protected\nverifier paths, native review requirements, break-glass constraints, and the\nexplicit trust boundary.\n\n## Trust boundary and non-claims\n\nThe trusted computing base contains GitHub service integrity, retained\norganization-owner recovery custody, the `kungfu-origin` review/governance\nidentity, the exact Buildchain verifier, and official publication identities.\nThe protocol does not claim resistance to compromise of GitHub itself,\ncompromise of all retained owner and recovery anchors, or malicious control of\nall independent trust anchors. A governance receipt grants no GitHub\npermission and is not a bearer credential.\n\n`dongkeren` is the development and pull-request author identity.\n`kungfu-origin` is the independent Code Owner and governance identity. A\nqualifying receipt requires the development identity to be active without an\nadministrator or maintainer role and requires the review identity to retain the\nadmitted governance role. Account recovery and retained root custody remain\noutside normal contributor and workflow paths.\n\n## Effective policy\n\nThe verifier evaluates native provider layers together. Every authoritative\ntarget must require:\n\n- a pull request, at least one independent Code Owner approval, and a fresh\n  approval after the latest reviewable push;\n- administrator enforcement, resolved review conversations, and a non-empty\n  required-check set whose exact contexts, GitHub App producer identities, and\n  strict-update setting match the versioned target policy;\n- no unapproved bypass actor, force push, or protected-ref deletion. Managed\n  dev/alpha/release ref bookkeeping may admit only the exact GitHub Actions App\n  identity versioned for that target; user and team bypass actors remain\n  non-qualifying;\n- exact last-match ownership of CODEOWNERS and the governance descriptor,\n  collector, rollout planner, and scheduled audit workflow;\n- complete readable GitHub API evidence. Missing, forbidden, ambiguous, or\n  malformed provider state is non-qualifying.\n\nRepository and organization rulesets are additive to classic branch\nprotection. Inspecting only one layer is insufficient because an applicable\nbypass or weaker update path in another layer can invalidate the effective\npolicy.\n\n## Repository and plan admission\n\nThe 2026-07-24 baseline contains 16 managed repositories: 13 public and three\nprivate. Public repository names are versioned in the descriptor. Private\nrepository names are never emitted in public evidence; their identities are\nrepresented by stable roots derived from the GitHub provider repository ID,\nindependent of the governance policy root. This prevents a policy revision from\nchanging repository identity or creating a circular admission dependency. A\nnewly discovered repository or target ref is non-authoritative until explicitly\nadmitted.\n\nThe descriptor also versions every active public merge target. The full audit\nevaluates one receipt per authoritative target rather than assuming the default\nbranch represents dev, alpha, release, or major publish-gate branches. The live\ndefault branch is always included even if it drifts outside the registry, in\nwhich case it is non-qualifying. Retained historical channels and generated\nper-release publish-gate refs are not silently deleted or promoted to current\nauthority; they require an explicit registry revision before they can qualify.\n\nFor an admitted private repository, the active target set is the current\ndefault branch plus existing alpha/release siblings on the same version line.\nIts required-check bindings remain non-qualifying until their sanitized binding\nroots are sealed into the private identity entry after supported native\nprotection exists.\n\nPublic repositories can qualify on supported Free, Team, or Enterprise\nenforcement. Private repositories and organization-wide rules require Team or\nEnterprise capability. On an unsupported plan they remain explicitly\n`non-authoritative-plan-capability-required` and publication-ineligible. The\nverifier does not replace missing native enforcement with CI or documentation,\nand the implementation never makes a private repository public as a\nworkaround.\n\n## Read-only audit\n\nRun the organization audit without mutation:\n\n```bash\nbuildchain audit github-governance \\\n  --organization kungfu-systems \\\n  --output github-governance.json \\\n  --json\n```\n\nLimit a canary to one repository:\n\n```bash\nbuildchain audit github-governance \\\n  --repository kungfu-systems/buildchain \\\n  --target-ref dev/v2/v2.14 \\\n  --require-qualifying \\\n  --json\n```\n\nProtected merge and publication consumers verify the receipt against the exact\nrepository, target base ref, policy root, freshness window, and exact\nBuildchain verifier source revision. Non-dry-run publication does not trust a\ncaller-supplied JSON hash: it mints a bounded token for the dedicated read-only\ngovernance auditor GitHub App, recollects live provider state with the exact\nBuildchain runtime, requires the resulting single-repository/single-target\naudit to qualify, and consumes that independently generated receipt. Missing\nApp configuration or unreadable provider state denies publication before\nprovider mutation. The publication authority workflow is itself an explicit\nCode Owner path.\n\nThe publication authority job and every reusable-workflow caller grant the\nbuilt-in `GITHUB_TOKEN` only `actions: read`, `checks: read`, `contents: read`,\nand `pull-requests: read`. The dedicated auditor App independently recollects\nthe organization-wide governance receipt, while these job-scoped permissions\nallow the exact publication transaction audit to resolve required check runs\nand merged pull-request review lineage. Omitting either read permission makes\nthe transaction evidence incomplete and therefore non-qualifying.\n\nThe output is sanitized. Public repositories retain their public identity.\nPrivate repositories expose only an identity root, visibility class, target\nref, sanitized required-check bindings and fact roots, and a qualifying or\nnon-qualifying decision. Tokens, cookies, recovery material, private\nCODEOWNERS bytes, raw permission payloads, and credential-bearing URLs are\nnever included.\n\n## Mutation and rollback boundary\n\nLive role, ruleset, branch-protection, Actions, Environment, or repository\nchanges are separate from audit. Every mutation starts from a read-only\ninventory and a frozen rollback snapshot. A rollout plan binds both roots and\nlists the exact API operation, impact, expected observation, and inverse\noperation. Apply must stop on the first unexplained drift and must perform a\npost-change read-back before continuing to the next bounded canary.\n\nPlan one exact branch without mutation:\n\n```bash\nbuildchain github-governance plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.14 \\\n  --required-check check \\\n  --required-check-app-id check=15368 \\\n  --required-approvals 1 \\\n  --snapshot-output rollback.json \\\n  --plan-output rollout.json\n```\n\nAn already protected check preserves its observed GitHub App binding. Every new\nrequired check must declare `--required-check-app-id <context>=<app-id>`;\ncontext-only replacement is rejected because it would broaden which producer\ncan satisfy the gate.\n\nClassic branch-protection bypass allowances and ruleset bypass actors are both\npart of the effective policy. Reconciliation writes explicit empty user, team,\nand App bypass lists and verifies those lists after apply; omitting the provider\nfield is not treated as removal because GitHub may preserve the prior value.\n\nThe plan prints a `planRoot`. Apply requires that exact root and stops if live\nprotection no longer matches the frozen inventory:\n\n```bash\nbuildchain github-governance apply \\\n  --plan-json rollout.json \\\n  --confirm-plan-root sha256:...\n```\n\nRollback is separately explicit and root-bound:\n\n```bash\nbuildchain github-governance rollback \\\n  --plan-json rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, classic branch protection can also be compiled\ndirectly from the authority descriptor. This mode preserves both App-bound\nchecks and intentionally unbound check contexts such as Kungfu alpha's\n`build`, rather than guessing a provider App identity.\n\n```bash\nbuildchain github-governance protection-policy-plan \\\n  --repository kungfu-systems/kungfu \\\n  --branch alpha/v4/v4.0 \\\n  --snapshot-output protection-rollback.json \\\n  --plan-output protection-rollout.json\n\nbuildchain github-governance protection-policy-apply \\\n  --plan-json protection-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance protection-policy-rollback \\\n  --plan-json protection-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, repository ruleset reconciliation compiles the\ntarget descriptor into the provider body. It replaces bypass actors with the\nexact provider-admitted desired set, requires fresh Code Owner approval and\nresolved review threads, and binds required checks plus strict-update semantics\nto the target policy. Newly synthesized managed rules include GitHub's explicit\ncanonical defaults so the frozen expected root matches provider read-back.\nRepository rulesets default to no bypass actors. The\ndescriptor's target-bound GitHub Actions allowance is an upper bound on\neffective provider state, not a requirement to add that actor to every\nprotection layer; when needed, the built-in App allowance is expressed by\nclassic branch protection. The target condition must contain exactly one\nbranch; unrelated rules and conditions are preserved in place.\n\n```bash\nbuildchain github-governance ruleset-policy-plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch alpha/v2/v2.14 \\\n  --ruleset-id 19518955 \\\n  --snapshot-output ruleset-rollback.json \\\n  --plan-output ruleset-rollout.json\n\nbuildchain github-governance ruleset-policy-apply \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance ruleset-policy-rollback \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nThe narrower `ruleset-plan` mode changes only `bypass_actors`; it remains\navailable for a bypass-only canary, but it cannot prove that an effective\nruleset matches the target descriptor. Both modes require the frozen ruleset\nsnapshot root for rollback.\n\nPaid-plan purchase, billing, legal/account-owner decisions, and any operation\nthat could remove the last recoverable owner remain external human gates.\nBreak-glass is disabled by default and, if ever admitted, must be separately\nauthenticated, reason-bound, time-bounded, independently receipted, and\nfollowed by mandatory restoration and root comparison."
     },
     {
       "id": "manual:homebrew",

package/dist/site/public-surface-audit.json

@@ -2154,6 +2154,7 @@
           "branch-protection-bypass-users",
           "dry-run",
           "expected-publication-version",
+          "generated-pull-request-token",
           "generated-ref-update-token",
           "generated-status-check-token",
           "github-release",
@@ -2212,7 +2213,7 @@
           "transaction-state-path",
           "verification-command"
         ],
-        "inputCount": 63
+        "inputCount": 64
       },
       {
         "id": "report-buildchain-issue",
@@ -3909,8 +3910,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "5ba7fd93a13993b05767b6f02d0626a7347f25c3d7cd4589ed4f70028c1f1bd1",
-    "workflowRegistryDigest": "1c2d1662c528b7762c45f626b815387430b89f8d062085ca47fc7205460c12a5",
-    "pageRegistryDigest": "a078d91bbd656cc928e7210eaa83952a4f6eea61e319656434f963cfb86dc01b"
+    "workflowRegistryDigest": "c2abf629b205a96f536e8758c3d9cdb3eade6945294fe278774877ef41d90b60",
+    "pageRegistryDigest": "35cc8794b15ffe6e8927cad756821aabbcbf0287cbf78fdd59e1c4bf60d52f7b"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-24T11:35:01.198Z",
-  "publishedAt": "2026-07-24T11:35:01.198Z",
+  "generatedAt": "2026-07-24T12:46:36.499Z",
+  "publishedAt": "2026-07-24T12:46:36.499Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "b5f602c1f99af9b4177dd26b5c12ffd4ad90a497",
+  "sourceRevision": "13b001a82ed1e6845b864028e0cce5b72c5d36c7",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.18-alpha.3",
+    "version": "2.14.18-alpha.5",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-24T11:35:01.198Z",
-  "publishedAt": "2026-07-24T11:35:01.198Z",
+  "generatedAt": "2026-07-24T12:46:36.499Z",
+  "publishedAt": "2026-07-24T12:46:36.499Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "b5f602c1f99af9b4177dd26b5c12ffd4ad90a497",
+  "sourceRevision": "13b001a82ed1e6845b864028e0cce5b72c5d36c7",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.18-alpha.3",
+    "version": "2.14.18-alpha.5",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -93,7 +93,7 @@
       "path": "docs/github-governance-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:3103d7982c9a30b344c603566520aeb1d5d90c1c54958d9c1c2b7ae897359da8"
+      "digest": "sha256:8484b18d5b0fe6d61d102d6b9cb9e18beac9f47ecb516d430fb5427518e2931f"
     },
     {
       "id": "release-candidate",

package/dist/site/workflow-registry.json

@@ -1867,6 +1867,7 @@
         "branch-protection-bypass-users",
         "dry-run",
         "expected-publication-version",
+        "generated-pull-request-token",
         "generated-ref-update-token",
         "generated-status-check-token",
         "github-release",
@@ -1925,7 +1926,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 63,
+      "inputCount": 64,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/github-governance-authority.md

@@ -140,6 +140,14 @@ App configuration or unreadable provider state denies publication before
 provider mutation. The publication authority workflow is itself an explicit
 Code Owner path.
 
+The publication authority job and every reusable-workflow caller grant the
+built-in `GITHUB_TOKEN` only `actions: read`, `checks: read`, `contents: read`,
+and `pull-requests: read`. The dedicated auditor App independently recollects
+the organization-wide governance receipt, while these job-scoped permissions
+allow the exact publication transaction audit to resolve required check runs
+and merged pull-request review lineage. Omitting either read permission makes
+the transaction evidence incomplete and therefore non-qualifying.
+
 The output is sanitized. Public repositories retain their public identity.
 Private repositories expose only an identity root, visibility class, target
 ref, sanitized required-check bindings and fact roots, and a qualifying or

package/package.json

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

package/scripts/generate-channel-promotion-workflow.mjs

@@ -209,6 +209,7 @@ permissions:
   contents: write
   id-token: write
   issues: write
+  pull-requests: write
 
 jobs:
   resolve-promotion:
@@ -409,6 +410,7 @@ jobs:
       contents: write
       id-token: write
       issues: write
+      pull-requests: write
     with:
 ${alphaForwarded}
     secrets: inherit
@@ -424,6 +426,7 @@ ${alphaForwarded}
       contents: write
       id-token: write
       issues: write
+      pull-requests: write
     with:
 ${stableForwarded}
     secrets: inherit