@kungfu-tech/buildchain 3.0.9-alpha.16 → 3.0.9-alpha.17

package/dist/site/page-registry.json

@@ -167,7 +167,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/promote-buildchain-ref/README.md",
-      "digest": "sha256:ac201757991983f457e7216e24581c39294fa03987b59059b4fa833aa8d6958d",
+      "digest": "sha256:1e17b0b58aafb7f38f29eb43234662b566ffdaa75bec8adb88c1bd1fbe390dfb",
       "headings": [
         {
           "level": 1,
@@ -185,7 +185,7 @@
           "anchor": "publish-transactions"
         }
       ],
-      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-ref-promotion-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v3/v3.0` creates or reuses the next exact prerelease tag such as\n  `v3.0.3-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v3.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;\n- `release/v3/v3.0` creates or reuses the next exact release tag such as\n  `v3.0.2`, 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 `v3.0.3-alpha.0` and\n  points the alpha/dev channel branches plus `v3.0-alpha` at that prerelease\n  commit, and moves `v3-alpha` only if no higher v3 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v3/v3.0`, writes the next major production version such as\n  `v4.0.0`, points `publish-gate/major`, `release/v4/v4.0`, `v4.0`, and `v4`\n  at that release commit, then prepares `v4.0.1-alpha.0` for\n  `alpha/v4/v4.0`, `dev/v4/v4.0`, `v4.0-alpha`, and `v4-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/v3/v3.1` creates `v3.1.N`, promotes `v3.1`, and promotes `v3` only\nwhen the next minor tag such as `v3.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\nWhen the requested version already matches every declared version-state file,\ndry-run planning still runs `lifecycle.version-state` and any explicit\n`verification-command` so it can discover declared derived material. It does\nnot fall back to the repository-wide `lifecycle.verify` in that no-op case;\nfull product verification can require candidate artifacts that are deliberately\nnot present until the later admission phase. Non-dry-run version-state writes\ncontinue to require the configured verification lifecycle before any ref moves.\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\nGitHub may return either `403` or a deliberately opaque `404` when a\nnon-administrator token reads the full branch-protection endpoint. In that\ncase, promotion reads the provider's branch summary and accepts only an\nalready-protected branch that enforces the exact required check for everyone.\nIt does not interpret the opaque response as missing protection or try to\nrewrite policy with a developer token. The independent publication-authority\naudit remains responsible for the complete read-only governance proof.\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@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v3/v3.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\":\"3.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@v3\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@v3\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    release-candidate-family-evidence-required: \"true\"\n    release-candidate-family-evidence-root: sha256:<initiative-family-root>\n    release-candidate-family-initiative-id: 2026-07-30-example-initiative\n    release-candidate-family-assignment-id: 2026-07-30-example-release\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\nThe four family-evidence inputs are optional. When enabled, the action requires\nthe candidate passport to carry the exact\n`kungfu-buildchain-initiative-family-release-evidence/v1` envelope and checks\nits family root, Initiative id, and Assignment id before any promotion\nmutation. Buildchain only transports and validates this adapter-edge release\nevidence; Kungfu Work Control remains authoritative for native Family State v1\nand its additive v2 typed envelope.\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\nBuild-once callers additionally pass `publish-sealed-bundle-root` and\n`publish-sealed-bundle-manifest`. The action verifies the typed manifest and\npersists every declared file below\n`sealed-bundle/<candidate-root>/files/` on the same durable ref before it starts\nthe publish command. A fresh runner can omit both inputs: the action restores\nthe exact binary bundle into `.buildchain/recovered-publication/<version>/`,\nre-verifies it, and exports the recovered npm tarball through\n`BUILDCHAIN_SEALED_NPM_TARBALL` with its exact integrity and SHA-256. This path\nnever repacks the npm tarball.\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_SEALED_BUNDLE_ROOT\nBUILDCHAIN_SEALED_NPM_TARBALL\nBUILDCHAIN_SEALED_NPM_INTEGRITY\nBUILDCHAIN_SEALED_NPM_SHA256\nBUILDCHAIN_REQUIRED_ARTIFACTS\nBUILDCHAIN_PUBLISH_REQUIRED_ARTIFACTS_PATH\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.\nThe action also writes that normalized array to\n`BUILDCHAIN_PUBLISH_REQUIRED_ARTIFACTS_PATH`. To stay below operating-system\nprocess environment limits, large arrays are available through the file path\nonly; small arrays retain the inline variable for compatibility.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-publication-state`, `transaction-sealed-bundle-root`,\n`transaction-resume-command`,\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`transaction-publication-state` provides the stable\n`prepared`, `sealed`, `package-published`, `alpha-complete`, or\n`release-complete` operator view. `transaction-resume-command` is the exact\nconsumer-facing resume entrypoint bound into the sealed manifest.\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. When sealed release assets are present, those restored\nfiles replace caller-supplied artifact paths. After upload succeeds, the action\nwrites the `github_release` milestone back to the durable transaction; an\ninterruption before that write is safe to retry because release creation and\nasset replacement are idempotent.\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-adopter-delivery-json` to a passed protocol-neutral\nadopter delivery gate result. Buildchain roots the exact product, artifact,\ndriver, profile, and semantic report closure into both the Release Passport and\nartifact evidence; either-copy substitution fails release verification.\nSet `release-passport-kfd-adopter-manifest-json` to the standard full-cut\nadopter manifest and `release-passport-kfd-product-gate-jsons` to the\nnewline-separated KFD-4, KFD-5, and KFD-7 gate results. Buildchain binds the\nexact published KFD package, registry, verifier set, source, decision witness,\nand product-gate roots into both Passport and artifact evidence. The optional\n`release-passport-kfd-support-matrix-json` is comparison-only; it must exactly\nmatch the derived `kfd-support.json` compatibility projection and cannot widen\ncandidate, unsupported, draft, or non-shipped states.\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.\nSet `release-passport-evidence-jsons` to newline-separated product-owned release\nevidence attachment indexes. Each JSON document must declare `schemaVersion`, a\nstable `id`, a product contract, and the exact release source SHA, tag, and\nchannel. Buildchain copies and hashes the documents, verifies their coordinates\nagainst the final Passport, and retains them in the release evidence bundle\nwithout interpreting product-specific or legal claims.\n\nWhen release coordinates are not known until promotion, set\n`release-passport-attachment-command`. Buildchain supplies\n`BUILDCHAIN_RELEASE_SOURCE_SHA`, `BUILDCHAIN_RELEASE_TAG`,\n`BUILDCHAIN_RELEASE_CHANNEL`, `BUILDCHAIN_RELEASE_VERSION`,\n`BUILDCHAIN_RELEASE_DEPLOYMENT_COORDINATE`, `BUILDCHAIN_RELEASE_TARGET_REF`, and\n`BUILDCHAIN_RELEASE_PASSPORT_OUTPUT_DIR`; the command must emit a JSON array or\nan object with a non-empty `files` array. Direct Action callers may still use\nthe v2 alias `release-passport-evidence-command`. Reusable v3 workflows reserve\nthat older name for the distinct post-activation released-evidence command.\n\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.\nSet `release-passport-github-artifact-attestation-policy-jsons` to one or more\nnewline-separated `buildchain.github-artifact-attestation-policy/v1` paths when\nthe Release Passport must require GitHub keyless provenance for Linux release\nartifacts. The higher-level v3 promotion workflow exposes the single-artifact\n`github-artifact-attestation-policy-json` input and owns staging, signing,\nprovider verification, immutable GitHub Release evidence upload, and read-back;\ndirect action callers own those post-Passport steps themselves.\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`. An explicit recovery of an already `complete` transaction is also\naccepted when the requested source SHA, version, exact tag, channel, and target\nall match the durable record exactly. It returns the completed transaction\nwithout republishing package bytes; a source accepted only through later branch\nhistory is not sufficient for this terminal-state reuse.\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  an immutable recovery receipt may instead admit the exact current alpha\n  channel SHA only when its sealed candidate tree is byte-equivalent and its\n  publication version is bound by that receipt; when administrative protection\n  details are hidden, the provider-visible protected head and required check\n  must still match that exact recovered SHA;\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 `v3.0` and `v3`, and floating alpha\ntags are minor-line tags such as `v3.0-alpha` plus cross-minor major tags such\nas `v3-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 `v3.0-alpha` and `v3-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": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-ref-promotion-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v3/v3.0` creates or reuses the next exact prerelease tag such as\n  `v3.0.3-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v3.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;\n- `release/v3/v3.0` creates or reuses the next exact release tag such as\n  `v3.0.2`, 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 `v3.0.3-alpha.0` and\n  points the alpha/dev channel branches plus `v3.0-alpha` at that prerelease\n  commit, and moves `v3-alpha` only if no higher v3 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v3/v3.0`, writes the next major production version such as\n  `v4.0.0`, points `publish-gate/major`, `release/v4/v4.0`, `v4.0`, and `v4`\n  at that release commit, then prepares `v4.0.1-alpha.0` for\n  `alpha/v4/v4.0`, `dev/v4/v4.0`, `v4.0-alpha`, and `v4-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/v3/v3.1` creates `v3.1.N`, promotes `v3.1`, and promotes `v3` only\nwhen the next minor tag such as `v3.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\nWhen the requested version already matches every declared version-state file,\ndry-run planning still runs `lifecycle.version-state` and any explicit\n`verification-command` so it can discover declared derived material. It does\nnot fall back to the repository-wide `lifecycle.verify` in that no-op case;\nfull product verification can require candidate artifacts that are deliberately\nnot present until the later admission phase. Non-dry-run version-state writes\ncontinue to require the configured verification lifecycle before any ref moves.\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\nGitHub may return either `403` or a deliberately opaque `404` when a\nnon-administrator token reads the full branch-protection endpoint. In that\ncase, promotion reads the provider's branch summary and accepts only an\nalready-protected branch that enforces the exact required check for everyone.\nIt does not interpret the opaque response as missing protection or try to\nrewrite policy with a developer token. The independent publication-authority\naudit remains responsible for the complete read-only governance proof.\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@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v3/v3.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\":\"3.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@v3\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@v3\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    release-candidate-family-evidence-required: \"true\"\n    release-candidate-family-evidence-root: sha256:<initiative-family-root>\n    release-candidate-family-initiative-id: 2026-07-30-example-initiative\n    release-candidate-family-assignment-id: 2026-07-30-example-release\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\nThe four family-evidence inputs are optional. When enabled, the action requires\nthe candidate passport to carry the exact\n`kungfu-buildchain-initiative-family-release-evidence/v1` envelope and checks\nits family root, Initiative id, and Assignment id before any promotion\nmutation. Buildchain only transports and validates this adapter-edge release\nevidence; Kungfu Work Control remains authoritative for native Family State v1\nand its additive v2 typed envelope.\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\nBuild-once callers additionally pass `publish-sealed-bundle-root` and\n`publish-sealed-bundle-manifest`. The action verifies the typed manifest and\npersists every declared file below\n`sealed-bundle/<candidate-root>/files/` on the same durable ref before it starts\nthe publish command. A fresh runner can omit both inputs: the action restores\nthe exact binary bundle into `.buildchain/recovered-publication/<version>/`,\nre-verifies it, and exports the recovered npm tarball through\n`BUILDCHAIN_SEALED_NPM_TARBALL` with its exact integrity and SHA-256. This path\nnever repacks the npm tarball.\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_SEALED_BUNDLE_ROOT\nBUILDCHAIN_SEALED_NPM_TARBALL\nBUILDCHAIN_SEALED_NPM_INTEGRITY\nBUILDCHAIN_SEALED_NPM_SHA256\nBUILDCHAIN_REQUIRED_ARTIFACTS\nBUILDCHAIN_PUBLISH_REQUIRED_ARTIFACTS_PATH\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.\nThe action also writes that normalized array to\n`BUILDCHAIN_PUBLISH_REQUIRED_ARTIFACTS_PATH`. To stay below operating-system\nprocess environment limits, large arrays are available through the file path\nonly; small arrays retain the inline variable for compatibility.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-publication-state`, `transaction-sealed-bundle-root`,\n`transaction-resume-command`,\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`transaction-publication-state` provides the stable\n`prepared`, `sealed`, `package-published`, `alpha-complete`, or\n`release-complete` operator view. `transaction-resume-command` is the exact\nconsumer-facing resume entrypoint bound into the sealed manifest.\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. When sealed release assets are present, those restored\nfiles replace caller-supplied artifact paths. After upload succeeds, the action\nwrites the `github_release` milestone back to the durable transaction; an\ninterruption before that write is safe to retry because release creation and\nasset replacement are idempotent.\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-adopter-delivery-json` to a passed protocol-neutral\nadopter delivery gate result. Buildchain roots the exact product, artifact,\ndriver, profile, and semantic report closure into both the Release Passport and\nartifact evidence; either-copy substitution fails release verification.\nSet `release-passport-kfd-adopter-manifest-json` to the standard full-cut\nadopter manifest and `release-passport-kfd-product-gate-jsons` to the\nnewline-separated KFD-4, KFD-5, and KFD-7 gate results. Buildchain binds the\nexact published KFD package, registry, verifier set, source, decision witness,\nand product-gate roots into both Passport and artifact evidence. The optional\n`release-passport-kfd-support-matrix-json` is comparison-only; it must exactly\nmatch the derived `kfd-support.json` compatibility projection and cannot widen\ncandidate, unsupported, draft, or non-shipped states.\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.\nSet `release-passport-evidence-jsons` to newline-separated product-owned release\nevidence attachment indexes. Each JSON document must declare `schemaVersion`, a\nstable `id`, a product contract, and the exact release source SHA, tag, and\nchannel. Buildchain copies and hashes the documents, verifies their coordinates\nagainst the final Passport, and retains them in the release evidence bundle\nwithout interpreting product-specific or legal claims.\n\nWhen release coordinates are not known until promotion, set\n`release-passport-attachment-command`. Buildchain supplies\n`BUILDCHAIN_RELEASE_SOURCE_SHA`, `BUILDCHAIN_RELEASE_TAG`,\n`BUILDCHAIN_RELEASE_CHANNEL`, `BUILDCHAIN_RELEASE_VERSION`,\n`BUILDCHAIN_RELEASE_DEPLOYMENT_COORDINATE`, `BUILDCHAIN_RELEASE_TARGET_REF`, and\n`BUILDCHAIN_RELEASE_PASSPORT_OUTPUT_DIR`; the command must emit a JSON array or\nan object with a non-empty `files` array. Direct Action callers may still use\nthe v2 alias `release-passport-evidence-command`. Reusable v3 workflows reserve\nthat older name for the distinct post-activation released-evidence command.\n\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.\nSet `release-passport-github-artifact-attestation-policy-jsons` to one or more\nnewline-separated `buildchain.github-artifact-attestation-policy/v1` paths when\nthe Release Passport must require GitHub keyless provenance for Linux release\nartifacts. The higher-level v3 promotion workflow exposes the single-artifact\n`github-artifact-attestation-policy-json` input and owns staging, signing,\nprovider verification, immutable GitHub Release evidence upload, and read-back;\ndirect action callers own those post-Passport steps themselves.\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`. An explicit recovery of an already `complete` transaction is also\naccepted when the requested source SHA, version, exact tag, channel, and target\nall match the durable record exactly. It returns the completed transaction\nwithout republishing package bytes; a source accepted only through later branch\nhistory is not sufficient for this terminal-state reuse.\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  the exact merge commit of another reviewed same-repository PR into that\n  protected alpha target is also accepted, while a commit merely contained by\n  an associated PR is not;\n  an immutable recovery receipt may instead admit the exact current alpha\n  channel SHA only when its sealed candidate tree is byte-equivalent and its\n  publication version is bound by that receipt; when administrative protection\n  details are hidden, the provider-visible protected head and required check\n  must still match that exact recovered SHA;\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 `v3.0` and `v3`, and floating alpha\ntags are minor-line tags such as `v3.0-alpha` plus cross-minor major tags such\nas `v3-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 `v3.0-alpha` and `v3-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:release-tail",
@@ -2130,7 +2130,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-delivery-warrant.md",
-      "digest": "sha256:172b2d56cad47086bff63fbd29c0eca58ddb48baac2f63b734fd3df3c99a9879",
+      "digest": "sha256:d7de9bf2aa94828f11c11868a6f110b886d50516881d14ccdc353abcb837b05f",
       "headings": [
         {
           "level": 1,
@@ -2168,7 +2168,7 @@
           "anchor": "workflow-rollout-and-rollback"
         }
       ],
-      "markdown": "---\nstatus: accepted\nperiod: ongoing\ntheme: dev-delivery-warrant\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-08-11\n  invisible_context: not asserted\n---\n\n# Dev Delivery Warrant Queue\n\nBuildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a\ndurable, non-preemptive delivery turn without replacing GitHub Merge Queue as\nthe final protected-ref authority.\n\nThe queue is stored on a dedicated Git ref below\n`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and\nadvances the ref without force. The transition receipt binds the expected old\nstate root; a competing controller receives a visible non-fast-forward failure\ninstead of a second authority claim.\n\n## Contract\n\nA submission binds the repository, protected dev line, pull request, semantic\nsource identity, exact source head, native Assignment and Initiative roots,\nsource patch or tree intent, reusable Source Qualification Proof, plan,\naffected closure, dependencies, toolchain, delivery class, priority, attempts,\nand retained enqueue time.\n\nSelection is deterministic FIFO plus aging with bounded priority. Priority may\nreorder queued work, but it cannot preempt the active Warrant. Exactly one\ncandidate receives a `provisional` leased Warrant containing a fencing token,\nlease generation, expected-old state root, expiry, and the complete exact\nsource binding. It reserves the next protected-dev landing before expensive\nnative shards start, but it is not GitHub Merge Queue admission authority.\nHeartbeat extends only that generation. Native proof success atomically\nupgrades the same token and generation to `qualified`; only then may enqueue\nbegin. Expiry fences further mutations by the old token, but it does not prove\nthat the old native process stopped. The active Warrant therefore remains in\nplace until bounded termination is proven by rooted terminal evidence. Only\nthat exact fenced settlement may clear the holder and permit successor\nselection.\n\nA terminal event may cancel a candidate before selection without minting a\nWarrant. This transition is limited to an exact non-active queued candidate and\nbinds its candidate root, pull request, recorded source head, event-observed\nsource head, terminal event action, evidence root, and expected-old queue root.\nAn active candidate still requires its current fencing token and lease\ngeneration. Exact duplicate cancellation evidence is a visible no-op; identity,\nstate, event, or evidence drift fails closed.\n\nThe reusable terminal controller classifies authoritative completion,\ncancellation, supersession, native failure, and transient dequeue separately.\n`dequeued` alone never clears an active Warrant: a fresh holder continues with\nthe same generation and token, while an expired holder waits for proof that its\nfenced worker stopped. Queued work may still settle as dequeued because it never\nstarted native execution. The controller uses one `settle` operation for active,\nqueued, already-terminal, and never-admitted pull requests. An active Warrant\nstill requires its exact fence and evidence. A matching queued cancellation is\npersisted normally. A duplicate terminal event or a pull request that never\nentered Warrant authority returns a rooted explicit no-op instead of failing\nthe workflow or inventing queue state.\n\nThe supported priority classes are `ordinary`, `expedited`, and `emergency`.\nThe queue does not infer an emergency: callers must choose it explicitly under\ntheir reviewed policy. Delivery classes are `non-native-fast`,\n`native-proof-required`, `cross-platform`, and `release`.\n\nA release-blocker candidate may additionally carry a rooted priority claim\ncreated from a settled Release Train dual landing. The claim binds the exact\nAssignment, Initiative, repair, prior and successor cuts, candidate generation,\ncut candidate, Dev head, semantic patch, both landing evidence roots, and\npublication gate. Only a claim whose repository, protected base, Work roots,\nhead, patch, and claim root match the queued candidate enters the blocker lane.\nThat lane outranks not-yet-leased ordinary work, but never preempts or rewrites\nan active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail\nclosed before selection.\n\n## Three proof authorities\n\nSource Qualification Proof is created from the cheap source-acceptance gate. It\nbinds the semantic source, exact source head and patch/tree intent, plan,\naffected closure, dependencies, toolchain, covered paths, and exact acceptance\nevidence. Ready state and approval are established before provisional\nselection.\n\nNative Qualification Proof is separate. Its v3 form binds semantic source and patch,\nplan, affected closure, dependency graph, toolchain, the exact execution\nenvironment contract, covered paths, native shard evidence, the exact dev\nbase used by the native composition, and the v2 native heartbeat-run receipt.\nThat receipt exposes and roots the exact repository, protected base, source\nhead, qualified base, toolchain, and environment binding established before\nprocess spawn. The proof repeats the binding root and includes the receipt root\nin its shard evidence. Before reuse, the consumer roots the\ncomplete attributed Dev delta, including both sides of every rename, then\nclassifies it:\n\n- unchanged semantic roots plus an unrelated fully attributed base delta reuse\n  native qualification and run only a cheap Project Cut replay. GitHub's `behind`\n  state is accepted only when a rooted replay proof binds the exact current\n  protected base, unchanged PR head and source patch, replay tree, required\n  context roots, and a qualified `project.cut.merge-queue-admission/v1`\n  receipt;\n- an overlapping delta reruns affected native shards or the full native plan;\n- an unknown or truncated graph, ambiguous rename, missing attribution, or\n  changed source, plan, closure, dependency, toolchain, or environment root\n  fails closed to full native qualification.\n\nHistorical Native Qualification Proof v1 and v2 values remain readable, but\nthey cannot be reused because their execution receipt did not bind the\nenvironment root. They fail closed to explicit native revalidation and produce\na v3 proof.\n\nThe reuse decision binds the exact old and current Dev heads, normalized changed\npaths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of\nthe same inputs byte-deterministic. Generated outputs that participate in the\naffected closure must be listed in `affected-paths-json`; a delta touching one\nof those surfaces is overlap, not a documentation-only advance.\n\nIntegration Delivery Proof is separate and cannot be cached across candidates.\nIt binds the exact current dev base, replay tree, GitHub `merge_group` head and\ntree, active Warrant fencing generation, Source Qualification Proof root, and\nfinal required-context roots. GitHub's exact merge-group checks remain the\nfinal integration authority.\n\n## CLI\n\nQueue commands are dry-run by default:\n\n```sh\nbuildchain dev warrant submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \\\n  --assignment-root <root> --initiative-root <root> \\\n  --source-identity-root <root> --source-patch-root <root> \\\n  --source-proof-root <root> --plan-root <root> --closure-root <root> \\\n  --dependency-root <root> --toolchain-root <root> \\\n  --environment-root <root> \\\n  --delivery-class native-proof-required\n\nbuildchain dev warrant select --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\n\nbuildchain dev proof native --branch dev/v4/v4.0 \\\n  --source-head <sha> --qualified-base <sha> \\\n  --environment-root <root> \\\n  --native-execution-receipt native-heartbeat-run.json \\\n  --affected-paths-json '[\"packages/native\"]' ...\n\nbuildchain dev proof classify-native --source-proof native-proof.json \\\n  --current-base <sha> --graph-known true --attribution-complete true \\\n  --changed-paths-json '[]' --renames-json '[]' ...\n\nbuildchain dev warrant qualify --repository owner/repository \\\n  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \\\n  --native-proof native-proof.json \\\n  --native-reuse-decision native-reuse-decision.json --execute\n\nbuildchain dev warrant cancel-queued --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \\\n  --expected-source-head <queued-sha> --observed-source-head <event-sha> \\\n  --expected-old <queue-root> --event-action closed --outcome cancelled \\\n  --evidence-root <terminal-event-root> --execute\n```\n\n`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.\nWarrant-scoped mutations require the exact fencing token and lease generation.\n`close` also requires a rooted terminal evidence object.\n\nExpensive native commands must run through `dev-delivery-native-run.mjs` (or an\nequivalent exact consumer). It performs an exact fenced heartbeat before spawn,\nrenews throughout the complete child lifetime, performs a final renewal before\naccepting success, and terminates the process group on heartbeat or fencing\nfailure. Missing, stale, expired, or mismatched Warrant state therefore blocks\nnative spawn instead of becoming qualification evidence. The environment root\nis validated and included in the execution binding before the first heartbeat\nor process spawn; it cannot be attached only after a successful run.\n\nProof commands create, verify, classify, and compose the two proof layers:\n\n```sh\nbuildchain dev proof source ...\nbuildchain dev proof classify --source-proof source-proof.json ...\nbuildchain dev proof replay ...\nbuildchain dev proof replay-proof \\\n  --qualification-receipt project-cut-admission.json ...\nbuildchain dev proof integration --warrant-result warrant.json ...\n```\n\n## Bounded-concurrency shadow qualification\n\nThe default production queue remains single-flight. A separate effect-disabled shadow\nplanner can replay the same deterministic candidate order with a bound of one\nor two lanes. It does not issue, renew, supersede, close, or persist a Warrant;\nit cannot enqueue a pull request; and its output explicitly carries no\nproduction or rollout authority.\n\nEach lane binds the exact queue root and generation, protected-base head,\nsource head, projected-base root, Project Cut, approval, required checks,\nstatus, and lease evidence. An active production candidate must additionally\nmatch its current fencing token and lease generation. A queued shadow lane must\nnot carry either. Stale evidence, an occupied native queue, cross-lane evidence\naliasing, shared conflict keys, or an incompatible projected base fails closed.\nA failure in one lane remains visible without converting or concealing the\nother lane's result.\n\nThe planner and aggregate qualification command consume immutable JSON files:\n\n```sh\nbuildchain dev warrant shadow-plan --input observation.json \\\n  --max-concurrency 2 --output shadow-plan.json\n\nbuildchain dev warrant shadow-qualify --input qualification-input.json \\\n  --output shadow-qualification.json\n```\n\nBoth commands reject `--execute`. Qualification reports compare explicit\nthresholds for sample count, eligible overlap, projected queue-wait benefit,\nadditional runner cost, ambiguity, and false positives. A `proceed` result is\nonly evidence for a separate reviewed rollout decision; it never changes the\nlive Warrant schema, queue state, merge-queue policy, or protected branch.\n\n## Opt-in bounded qualification and exclusive landing\n\nBuildchain also defines an explicit production opt-in that turns successful\nshadow evidence into a separate v2 authority state. It does not widen or\nreinterpret the v1 Warrant queue. The accepted\n[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)\nand `contracts/dev-delivery-authority-v2.schema.json` are authoritative.\n\nIn `bounded-qualification-landing` mode, a configured number of exact\nQualification Leases may coexist. Each lease carries\n`authority = qualification-only` and `mergeGroupAdmission = false`. Completing\nqualification records evidence and releases that lease. Qualified candidates\nthen wait for the one `Landing Warrant`, which alone carries\n`authority = merge-group-admission` and may be checked for `merge_group`\nadmission.\n\nConcurrency is granted only across disjoint rooted `qualificationDomains`.\nOverlap and unknown domains are held behind the active safety boundary with an\nexplicit content-rooted reason. `maxLandingOvertakes` prevents a slow older\ncandidate from being bypassed indefinitely, while `maxQualificationAttempts`\nturns repeated heartbeat loss into a rooted terminal failure. Every release\nreturns a deterministic rooted wake instruction; an exact duplicate release or\nrecovery is a state-root-preserving no-op.\n\nThe public command family is explicit:\n\n```sh\nbuildchain dev authority migrate --repository owner/repository \\\n  --branch dev/v3/v3.0 --legacy-state v1-queue.json --execute --json\nbuildchain dev authority lease-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority complete-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --evidence-root <qualification-root> --execute\nbuildchain dev authority lease-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority recover --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority admit-merge-group --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --merge-group-head <sha>\n```\n\nTerminal settlement releases either authority immediately from exact evidence;\nit does not wait for TTL. Exact duplicate settlement is a state-root-preserving\nno-op. The default `buildchain dev warrant` commands, v1 state bytes, and\nsingle-flight behavior do not change while this mode is off.\n\n## Workflow rollout and rollback\n\nThe reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:\n\n- `off` preserves the previous exact-head admission controller;\n- `shadow` qualifies the source and emits a read-only queue submission plan;\n- `required` persists the submission, selects a provisional Warrant, runs or\n  reuses semantic native proof under heartbeat, atomically qualifies the same\n  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and\n  selected candidate all pass exact readback validation. Immediately before\n  enqueue, the controller also rereads the current protected state ref and\n  verifies the active candidate, fencing token, generation, pull request, and\n  exact head. A previously valid result is not authority after terminal\n  closeout. Re-running qualification for the same selected head may regenerate\n  timestamped proof bytes, but it retains the immutable active Warrant and its\n  originally selected proof instead of rewriting or rejecting that attempt.\n  Each candidate also retains the exact successful source workflow run. If a\n  controller discovers that another candidate owns the active Warrant, a\n  configured consumer workflow is dispatched immediately for that exact PR,\n  head, and source run; the candidate is not left waiting for a patrol cron.\n\nFor a required native delivery class, the reusable controller rejects a\nmissing or malformed environment root before runtime checkout, candidate\nsubmission, Warrant selection, or native execution. The input remains\nconditionally optional so `off`, `shadow`, and `non-native-fast` callers keep\ntheir documented behavior.\n\nThe controller persists a completed native proof before its final base\nreclassification. A later exact retry can supply that proof and avoid the\nexpensive native command when the rooted delta still proves reuse safe. A\nduplicate dispatch against the same already-qualified Warrant returns the same\nproof and reuse roots without another queue mutation. Both result forms carry\n`landingAuthority: false`: only the live qualified Warrant plus exact-head\nGitHub merge-queue admission can authorize landing.\n\nThe required controller checks the protected base again after native work. A\ndisjoint attributed delta reuses the proof. Overlap or unknown attribution\ntriggers one automatic revalidation on the latest base; continued overlap,\nnative failure, cancellation, semantic head movement, or an unrecoverable merge\nconflict closes the exact fence. The next queued candidate is notified through\nthe `buildchain-dev-delivery-wake` repository event. Its complete semantic\ncandidate is carried under the single `client_payload.candidate` envelope so\nGitHub's ten-property top-level limit cannot discard proof bindings. If\ncancellation prevents cleanup, lease expiry recovers retained queue age and\nmints a new fence.\n\nConsumers should deploy `shadow` first, inspect receipts, then change their\nprotected caller to `required`. Rollback is a reviewed caller change back to\n`off`; it does not delete queue history or reinterpret old receipts. The\nterminal reusable workflow creates the exact Integration Delivery Proof for a\nmerged candidate (or accepts explicit evidence for another terminal outcome),\nthen closes only the current fencing generation. The separate queued\ncancellation reusable workflow cannot close an active generation; it advances\nthe state ref only when the caller's complete terminal binding and expected-old\nroot still match. A delayed `dequeued` event is ignored when GitHub readback\nshows the same exact PR head is already queued again, so an earlier queue event\ncannot close a newer active Warrant generation.\n\nBuildchain uses the same contract for its own protected dev line through\n`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and\nsemantic source roots, accepts an optional reusable native proof, pins the runtime to the caller commit, selects\n`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not\noffer an `off` switch: rollback is a reviewed change to this caller, not an\noperator-time weakening of a specific delivery attempt.\n\n`buildchain init --type native` generates the corresponding protected-dev\nconsumer workflow. It supports both explicit dispatch and the bounded wake\nevent, uses the same reusable controller, and keeps the native command in the\nconsumer repository rather than inventing provider-specific shards.\n\nThis mechanism schedules protected delivery only. It does not serialize local\ndevelopment, source-only checks, unrelated channels, release publication, or\nrunner provisioning. It never grants authority to enable cloud runner\ncampaigns."
+      "markdown": "---\nstatus: accepted\nperiod: ongoing\ntheme: dev-delivery-warrant\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-08-11\n  invisible_context: not asserted\n---\n\n# Dev Delivery Warrant Queue\n\nBuildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a\ndurable, non-preemptive delivery turn without replacing GitHub Merge Queue as\nthe final protected-ref authority.\n\nThe queue is stored on a dedicated Git ref below\n`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and\nadvances the ref without force. The transition receipt binds the expected old\nstate root; a competing controller receives a visible non-fast-forward failure\ninstead of a second authority claim.\n\n## Contract\n\nA submission binds the repository, protected dev line, pull request, semantic\nsource identity, exact source head, native Assignment and Initiative roots,\nsource patch or tree intent, reusable Source Qualification Proof, plan,\naffected closure, dependencies, toolchain, delivery class, priority, attempts,\nand retained enqueue time.\n\nSelection is deterministic FIFO plus aging with bounded priority. Priority may\nreorder queued work, but it cannot preempt the active Warrant. Exactly one\ncandidate receives a `provisional` leased Warrant containing a fencing token,\nlease generation, expected-old state root, expiry, and the complete exact\nsource binding. It reserves the next protected-dev landing before expensive\nnative shards start, but it is not GitHub Merge Queue admission authority.\nHeartbeat extends only that generation. Native proof success atomically\nupgrades the same token and generation to `qualified`; only then may enqueue\nbegin. Expiry fences further mutations by the old token, but it does not prove\nthat the old native process stopped. The active Warrant therefore remains in\nplace until bounded termination is proven by rooted terminal evidence. Only\nthat exact fenced settlement may clear the holder and permit successor\nselection.\n\nA terminal event may cancel a candidate before selection without minting a\nWarrant. This transition is limited to an exact non-active queued candidate and\nbinds its candidate root, pull request, recorded source head, event-observed\nsource head, terminal event action, evidence root, and expected-old queue root.\nAn active candidate still requires its current fencing token and lease\ngeneration. Exact duplicate cancellation evidence is a visible no-op; identity,\nstate, event, or evidence drift fails closed.\n\nThe reusable terminal controller classifies authoritative completion,\ncancellation, supersession, native failure, and transient dequeue separately.\n`dequeued` alone never clears an active Warrant: a fresh holder continues with\nthe same generation and token, while an expired holder waits for proof that its\nfenced worker stopped. Queued work may still settle as dequeued because it never\nstarted native execution. The controller uses one `settle` operation for active,\nqueued, already-terminal, and never-admitted pull requests. An active Warrant\nstill requires its exact fence and evidence. A matching queued cancellation is\npersisted normally. A duplicate terminal event or a pull request that never\nentered Warrant authority returns a rooted explicit no-op instead of failing\nthe workflow or inventing queue state.\n\nThe supported priority classes are `ordinary`, `expedited`, and `emergency`.\nThe queue does not infer an emergency: callers must choose it explicitly under\ntheir reviewed policy. Delivery classes are `non-native-fast`,\n`native-proof-required`, `cross-platform`, and `release`.\n\nA release-blocker candidate may additionally carry a rooted priority claim\ncreated from a settled Release Train dual landing. The claim binds the exact\nAssignment, Initiative, repair, prior and successor cuts, candidate generation,\ncut candidate, Dev head, semantic patch, both landing evidence roots, and\npublication gate. Only a claim whose repository, protected base, Work roots,\nhead, patch, and claim root match the queued candidate enters the blocker lane.\nThat lane outranks not-yet-leased ordinary work, but never preempts or rewrites\nan active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail\nclosed before selection.\n\n## Three proof authorities\n\nSource Qualification Proof is created from the cheap source-acceptance gate. It\nbinds the semantic source, exact source head and patch/tree intent, plan,\naffected closure, dependencies, toolchain, covered paths, and exact acceptance\nevidence. Ready state and approval are established before provisional\nselection.\n\nNative Qualification Proof is separate. Its v3 form binds semantic source and patch,\nplan, affected closure, dependency graph, toolchain, the exact execution\nenvironment contract, covered paths, native shard evidence, the exact dev\nbase used by the native composition, and the v2 native heartbeat-run receipt.\nThat receipt exposes and roots the exact repository, protected base, source\nhead, qualified base, toolchain, and environment binding established before\nprocess spawn. The proof repeats the binding root and includes the receipt root\nin its shard evidence. Before reuse, the consumer roots the\ncomplete attributed Dev delta, including both sides of every rename, then\nclassifies it:\n\n- unchanged semantic roots plus an unrelated fully attributed base delta reuse\n  native qualification and run only a cheap Project Cut replay. GitHub's `behind`\n  state is accepted only when a rooted replay proof binds the exact current\n  protected base, unchanged PR head and source patch, replay tree, required\n  context roots, and a qualified `project.cut.merge-queue-admission/v1`\n  receipt;\n- an overlapping delta reruns affected native shards or the full native plan;\n- an unknown or truncated graph, ambiguous rename, missing attribution, or\n  changed source, plan, closure, dependency, toolchain, or environment root\n  fails closed to full native qualification.\n\nHistorical Native Qualification Proof v1 and v2 values remain readable, but\nthey cannot be reused because their execution receipt did not bind the\nenvironment root. They fail closed to explicit native revalidation and produce\na v3 proof.\n\nThe reuse decision binds the exact old and current Dev heads, normalized changed\npaths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of\nthe same inputs byte-deterministic. Generated outputs that participate in the\naffected closure must be listed in `affected-paths-json`; a delta touching one\nof those surfaces is overlap, not a documentation-only advance.\n\nIntegration Delivery Proof is separate and cannot be cached across candidates.\nIt binds the exact current dev base, replay tree, GitHub `merge_group` head and\ntree, active Warrant fencing generation, Source Qualification Proof root, and\nfinal required-context roots. GitHub's exact merge-group checks remain the\nfinal integration authority.\n\n## CLI\n\nQueue commands are dry-run by default:\n\n```sh\nbuildchain dev warrant submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \\\n  --assignment-root <root> --initiative-root <root> \\\n  --source-identity-root <root> --source-patch-root <root> \\\n  --source-proof-root <root> --plan-root <root> --closure-root <root> \\\n  --dependency-root <root> --toolchain-root <root> \\\n  --environment-root <root> \\\n  --delivery-class native-proof-required\n\nbuildchain dev warrant select --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\n\nbuildchain dev proof native --branch dev/v4/v4.0 \\\n  --source-head <sha> --qualified-base <sha> \\\n  --environment-root <root> \\\n  --native-execution-receipt native-heartbeat-run.json \\\n  --affected-paths-json '[\"packages/native\"]' ...\n\nbuildchain dev proof classify-native --source-proof native-proof.json \\\n  --current-base <sha> --graph-known true --attribution-complete true \\\n  --changed-paths-json '[]' --renames-json '[]' ...\n\nbuildchain dev warrant qualify --repository owner/repository \\\n  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \\\n  --native-proof native-proof.json \\\n  --native-reuse-decision native-reuse-decision.json --execute\n\nbuildchain dev warrant cancel-queued --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \\\n  --expected-source-head <queued-sha> --observed-source-head <event-sha> \\\n  --expected-old <queue-root> --event-action closed --outcome cancelled \\\n  --evidence-root <terminal-event-root> --execute\n```\n\n`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.\nWarrant-scoped mutations require the exact fencing token and lease generation.\n`close` also requires a rooted terminal evidence object.\n\nExpensive native commands must run through `dev-delivery-native-run.mjs` (or an\nequivalent exact consumer). It performs an exact fenced heartbeat before spawn,\nrenews throughout the complete child lifetime, performs a final renewal before\naccepting success, and terminates the process group on heartbeat or fencing\nfailure. Missing, stale, expired, or mismatched Warrant state therefore blocks\nnative spawn instead of becoming qualification evidence. The environment root\nis validated and included in the execution binding before the first heartbeat\nor process spawn; it cannot be attached only after a successful run.\n\nProof commands create, verify, classify, and compose the two proof layers:\n\n```sh\nbuildchain dev proof source ...\nbuildchain dev proof classify --source-proof source-proof.json ...\nbuildchain dev proof replay ...\nbuildchain dev proof replay-proof \\\n  --qualification-receipt project-cut-admission.json ...\nbuildchain dev proof integration --warrant-result warrant.json ...\n```\n\n## Bounded-concurrency shadow qualification\n\nThe default production queue remains single-flight. A separate effect-disabled shadow\nplanner can replay the same deterministic candidate order with a bound of one\nor two lanes. It does not issue, renew, supersede, close, or persist a Warrant;\nit cannot enqueue a pull request; and its output explicitly carries no\nproduction or rollout authority.\n\nEach lane binds the exact queue root and generation, protected-base head,\nsource head, projected-base root, Project Cut, approval, required checks,\nstatus, and lease evidence. An active production candidate must additionally\nmatch its current fencing token and lease generation. A queued shadow lane must\nnot carry either. Stale evidence, an occupied native queue, cross-lane evidence\naliasing, shared conflict keys, or an incompatible projected base fails closed.\nA failure in one lane remains visible without converting or concealing the\nother lane's result.\n\nThe planner and aggregate qualification command consume immutable JSON files:\n\n```sh\nbuildchain dev warrant shadow-plan --input observation.json \\\n  --max-concurrency 2 --output shadow-plan.json\n\nbuildchain dev warrant shadow-qualify --input qualification-input.json \\\n  --output shadow-qualification.json\n```\n\nBoth commands reject `--execute`. Qualification reports compare explicit\nthresholds for sample count, eligible overlap, projected queue-wait benefit,\nadditional runner cost, ambiguity, and false positives. A `proceed` result is\nonly evidence for a separate reviewed rollout decision; it never changes the\nlive Warrant schema, queue state, merge-queue policy, or protected branch.\n\n## Opt-in bounded qualification and exclusive landing\n\nBuildchain also defines an explicit production opt-in that turns successful\nshadow evidence into a separate v2 authority state. It does not widen or\nreinterpret the v1 Warrant queue. The accepted\n[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)\nand `contracts/dev-delivery-authority-v2.schema.json` are authoritative.\n\nIn `bounded-qualification-landing` mode, a configured number of exact\nQualification Leases may coexist. Each lease carries\n`authority = qualification-only` and `mergeGroupAdmission = false`. Completing\nqualification records evidence and releases that lease. Qualified candidates\nthen wait for the one `Landing Warrant`, which alone carries\n`authority = merge-group-admission` and may be checked for `merge_group`\nadmission.\n\nConcurrency is granted only across disjoint rooted `qualificationDomains`.\nOverlap and unknown domains are held behind the active safety boundary with an\nexplicit content-rooted reason. `maxLandingOvertakes` prevents a slow older\ncandidate from being bypassed indefinitely, while `maxQualificationAttempts`\nturns repeated heartbeat loss into a rooted terminal failure. Every release\nreturns a deterministic rooted wake instruction; an exact duplicate release or\nrecovery is a state-root-preserving no-op.\n\nThe public command family is explicit:\n\n```sh\nbuildchain dev authority migrate --repository owner/repository \\\n  --branch dev/v3/v3.0 --legacy-state v1-queue.json --execute --json\nbuildchain dev authority lease-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority complete-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --evidence-root <qualification-root> --execute\nbuildchain dev authority lease-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority recover --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority admit-merge-group --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --merge-group-head <sha>\n```\n\nTerminal settlement releases either authority immediately from exact evidence;\nit does not wait for TTL. Exact duplicate settlement is a state-root-preserving\nno-op. The default `buildchain dev warrant` commands, v1 state bytes, and\nsingle-flight behavior do not change while this mode is off.\n\n## Workflow rollout and rollback\n\nThe reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:\n\n- `off` preserves the previous exact-head admission controller;\n- `shadow` qualifies the source and emits a read-only queue submission plan;\n- `required` persists the submission, selects a provisional Warrant, runs or\n  reuses semantic native proof under heartbeat, atomically qualifies the same\n  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and\n  selected candidate all pass exact readback validation. Immediately before\n  enqueue, the controller writes and then reads back both the exact-head queue\n  admission status and active lease status. Only after those statuses are\n  visible at their required states does it reread the pull request head,\n  protected base, native merge queue, and current protected Warrant state. The\n  final rooted admission transaction binds the frozen base, source head,\n  candidate, fencing token, generation, native proof roots, Project Cut proof,\n  and both status contexts. Status propagation is retried before enqueue;\n  base, head, queue-predecessor, lease, or Warrant drift revokes both statuses\n  without attempting enqueue. A previously valid result is not authority after terminal\n  closeout. Re-running qualification for the same selected head may regenerate\n  timestamped proof bytes, but it retains the immutable active Warrant and its\n  originally selected proof instead of rewriting or rejecting that attempt.\n  Each candidate also retains the exact successful source workflow run. If a\n  controller discovers that another candidate owns the active Warrant, a\n  configured consumer workflow is dispatched immediately for that exact PR,\n  head, and source run; the candidate is not left waiting for a patrol cron.\n\nFor a required native delivery class, the reusable controller rejects a\nmissing or malformed environment root before runtime checkout, candidate\nsubmission, Warrant selection, or native execution. The input remains\nconditionally optional so `off`, `shadow`, and `non-native-fast` callers keep\ntheir documented behavior.\n\nThe controller persists a completed native proof before its final base\nreclassification. A later exact retry can supply that proof and avoid the\nexpensive native command when the rooted delta still proves reuse safe. A\nduplicate dispatch against the same already-qualified Warrant returns the same\nproof and reuse roots without another queue mutation. Both result forms carry\n`landingAuthority: false`: only the live qualified Warrant plus exact-head\nGitHub merge-queue admission can authorize landing.\n\nThe required controller checks the protected base again after native work. A\ndisjoint attributed delta reuses the proof. Overlap or unknown attribution\ntriggers one automatic revalidation on the latest base; continued overlap,\nnative failure, cancellation, semantic head movement, or an unrecoverable merge\nconflict closes the exact fence. The next queued candidate is notified through\nthe `buildchain-dev-delivery-wake` repository event. Its complete semantic\ncandidate is carried under the single `client_payload.candidate` envelope so\nGitHub's ten-property top-level limit cannot discard proof bindings. If\ncancellation prevents cleanup, lease expiry recovers retained queue age and\nmints a new fence.\n\nConsumers should deploy `shadow` first, inspect receipts, then change their\nprotected caller to `required`. Rollback is a reviewed caller change back to\n`off`; it does not delete queue history or reinterpret old receipts. The\nterminal reusable workflow creates the exact Integration Delivery Proof for a\nmerged candidate (or accepts explicit evidence for another terminal outcome),\nthen closes only the current fencing generation. The separate queued\ncancellation reusable workflow cannot close an active generation; it advances\nthe state ref only when the caller's complete terminal binding and expected-old\nroot still match. A delayed `dequeued` event is ignored when GitHub readback\nshows the same exact PR head is already queued again, so an earlier queue event\ncannot close a newer active Warrant generation.\n\nBuildchain uses the same contract for its own protected dev line through\n`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and\nsemantic source roots, accepts an optional reusable native proof, pins the runtime to the caller commit, selects\n`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not\noffer an `off` switch: rollback is a reviewed change to this caller, not an\noperator-time weakening of a specific delivery attempt.\n\n`buildchain init --type native` generates the corresponding protected-dev\nconsumer workflow. It supports both explicit dispatch and the bounded wake\nevent, uses the same reusable controller, and keeps the native command in the\nconsumer repository rather than inventing provider-specific shards.\n\nThis mechanism schedules protected delivery only. It does not serialize local\ndevelopment, source-only checks, unrelated channels, release publication, or\nrunner provisioning. It never grants authority to enable cloud runner\ncampaigns."
     },
     {
       "id": "manual:dev-qualification-patrol",
@@ -3855,7 +3855,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/release-governance.md",
-      "digest": "sha256:889955042854bb95bc5dd58d2bdd26bdc8259c096e15c0a8d479289ff51448b8",
+      "digest": "sha256:66eca6c682edd21deeeaae769bcd6882f8fc70b6f9448abec9ed922d2a47ad97",
       "headings": [
         {
           "level": 1,
@@ -3948,7 +3948,7 @@
           "anchor": "operational-reading-order"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-release-governance\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  invisible_context: not asserted\n---\n\n# Release Governance\n\nBuildchain v3 preserves the release semantics of the older ABV workflow while\nmoving the implementation into one modern repository.\n\nThe central idea is simple: a reviewed merge into a release channel is the\nrelease intent. Automation must then create the version-state commit, exact tag,\nfloating tag, and next alpha state that make that intent true in Git.\n\n## Design Problem\n\nKungfu release automation has to keep four facts aligned:\n\n1. The source tree that was reviewed.\n2. The package version recorded in manifests such as `package.json` or\n   `lerna.json`.\n3. The exact immutable release or prerelease tag.\n4. The floating channel refs that consumers actually use.\n\nIf any one of these facts is updated by hand, the system can split:\n\n- a consumer can fetch `v3.0` and receive a tree whose package version still\n  says the previous release;\n- a maintainer can move `v3` without producing an exact `v3.0.N` audit tag;\n- an alpha can be promoted to production even though the release tree is not the\n  same tree that was tested;\n- a protected branch merge can succeed while the follow-up version commit is\n  missing, or a flow-internal generated `dev`/`alpha`/`release` ref update can\n  fail after publish because the automation identity was not declared in the\n  branch-protection review bypass allowance.\n\nThe older ABV workflow addressed this by letting GitHub PRs drive release\nstate. Buildchain keeps that choice because it makes release intent reviewable,\nobservable, and recoverable from Git history.\n\n## What ABV Contributed\n\nThe old ABV model was not just \"bump a version number.\" It encoded a governance\nloop:\n\n- release branches are named as channels: `dev`, `alpha`, `release`, and the\n  administrative `publish-gate/major`;\n- a PR from one channel to the next is the release request;\n- verify jobs check that the branch pair is valid before merge;\n- a maintainer review is required before the branch moves;\n- after merge, automation writes the version change and moves tags;\n- exact tags and floating refs are aligned with the resulting commit;\n- the next development channel is prepared automatically.\n\nABV also kept the version-state mutation in the repository. For JavaScript\nrepositories that usually meant changing `lerna.json` and/or `package.json`.\nThat commit is important because the tag alone is not enough evidence: the\nsource tree should also declare the version that the tag advertises.\n\nBuildchain v3 treats that as a hard semantic requirement for its own release\nline.\n\n## Buildchain Implementation\n\nBuildchain implements the same governance loop with:\n\n- `.github/workflows/release-verify.yml` for PR verification;\n- `.github/workflows/buildchain-ref-promotion.yml` for post-verify ref\n  promotion; this workflow dogfoods the declarative\n  `release-candidate-promote.yml` wrapper and does not hand-wire resolver,\n  artifact download, publish-gate, or promote action steps;\n- Buildchain self promotion enables `release-passport-buildchain-self-kfd`, so\n  the promote action generates KFD-1 witnesses, KFD-2 public claim JSON, and\n  KFD-3 collaboration-interface witnesses from the final version-state workspace\n  before release passport finalization. The witness hashes therefore bind to the\n  exact published package and site facts from\n  `packages/core/buildchain-kfd-claims.js` instead of relying on prose release\n  notes;\n- `actions/promote-buildchain-ref` for branch, tag, version-state, and\n  governance checks;\n- package-manager adapters that can update version state for pnpm, npm, and\n  yarn style repositories;\n- `buildchain.toml` lifecycle configuration for repositories whose version\n  state or verification commands are not Node package-manager defaults.\n\nThe implementation is intentionally stricter than a local release script:\n\n- manual workflow dispatch can only do dry-run promotion;\n- non-dry-run promotion must be driven by a completed `Verify` workflow;\n- target branch protection details must be readable, and branch protection must\n  apply to administrators as well as regular contributors;\n- `alpha/vX/vX.Y` and `release/vX/vX.Y` branch protection must require both the\n  general `check` context and the Release Verify aggregate `verify` context, so\n  an invalid channel pair cannot merge even when repository checks pass;\n- release targets keep those checks non-strict with respect to source-branch\n  ancestry: generated channel bookkeeping intentionally makes the source and\n  target histories diverge, while the pair-specific `verify` context validates\n  the legal channel transition;\n- alpha promotion must come from a merged same-repository PR from\n  `dev/vX/vX.Y` to `alpha/vX/vX.Y`;\n- release promotion must come from a merged same-repository PR from\n  `alpha/vX/vX.Y` to `release/vX/vX.Y`;\n- major promotion must come from a merged same-repository PR from\n  `release/vX/vX.Y` to `publish-gate/major`;\n- release promotion requires an existing same-patch alpha tag and checks the\n  release source tree against that tested alpha tree;\n- generated version-state commits are verified before refs move.\n\n## Reconciling a protected line without rebuilding\n\nThe public `build.yml` channel router ends with a top-level job named\n`Summarize build contract`. Keeping this aggregate at the public router boundary\nprevents its required check context from changing when the internal reusable\nbuild workflow gains another nesting layer.\n\nFor an already-tested pull request whose protected target still requires an\nolder Buildchain aggregate context, inspect the exact candidate SHA first:\n\n```bash\nGH_TOKEN=\"$(gh auth token)\" npx @kungfu-tech/buildchain@latest \\\n  release-governance reconcile \\\n  --repository kungfu-systems/example \\\n  --branch release/v3/v3.0 \\\n  --candidate-sha <tested-pr-head-sha> \\\n  --json\n```\n\nThe dry run reads the successful checks emitted for that SHA and reports the\nexact expected/actual context pair. It chooses the shallowest successful\n`Summarize build contract` context, so a new top-level router aggregate wins\nover the nested internal build summary. To apply the plan, rerun the same\ncommand with `--apply` using a token that can update branch protection.\n\nReconciliation changes only the required-status-check subresource. It replaces\nstale Buildchain aggregate contexts, preserves unrelated checks and strictness,\nand does not modify review requirements, administrator enforcement,\nconversation resolution, force-push policy, or deletion policy. The candidate\nmust still be the head of a pull request targeting the named managed branch;\nthe command fails closed otherwise. This lets a previously successful candidate\ncontinue from the same SHA without another native build or an administrator\nmerge bypass.\n\nRepositories may also expose a small caller workflow around\n`.github/workflows/release-governance-reconcile.yml@v3`. Pass `branch`,\n`candidate-sha`, and `apply`, and provide `governance-token` through the caller's\nsecrets. The reusable workflow uploads the JSON reconciliation receipt.\n\nExact publication planning installs the checked-out promotion source's declared\ndependencies before version-state verification. This keeps the pre-authority\nversion plan on the same package-manager boundary as the later promotion job,\nincluding repositories whose verification commands import production packages.\nThe planning pass may materialize and verify declared derived files locally,\nbut dry-run never creates Git blobs, trees, commits, refs, or tags.\n\nPromotion intents are serialized globally per caller repository with\n`cancel-in-progress: false`. A queued intent re-reads its protected target ref\nbefore checkout, dependency installation, release-candidate resolution, or any\npublish-gate/ref mutation. If the ref already points at a newer SHA, that older\nintent is no longer release authority: the workflow records the requested and\ncurrent SHAs, proves that the current target is ahead of the requested commit,\nand completes as a `target-ref-advanced` superseded no-op. Diverged or behind\ncomparisons are not superseded transactions and still fail closed.\nMissing refs, unreadable repository state, invalid channels, governance\nfailures, and artifact mismatches still fail closed. The promote action repeats\nthe target check at the mutation boundary, so a ref that advances after the\nworkflow preflight cannot receive a second set of publication side effects.\n\n## Version Lines\n\nKungfu uses Python-like version lines where a minor line can represent a\nlong-lived product train. A line such as `v3.0` can produce many production\npatch releases:\n\n```text\nv3.0.0\nv3.0.1\nv3.0.2\n...\nv3.0.1234\n```\n\nThis is why Buildchain maintains both exact and floating refs:\n\n- `v3.0.2` is immutable release evidence;\n- `v3.0` is the latest production release on the `3.0` line;\n- `v3` is the selected stable major-line entrypoint;\n- `v3.0.3-alpha.0` is immutable alpha evidence;\n- `v3.0-alpha` is the latest test channel for the `3.0` line.\n- `v3-alpha` is the latest test channel on the highest published alpha minor in major `3`.\n\nA release does not mean \"minor is complete.\" It means \"this patch on this minor\nline is now production.\"\n\nGitHub repository rules must preserve that distinction. Exact tags such as\n`v3.0.2` and `v3.0.3-alpha.0` should be immutable. Floating channel tags such as\n`v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion\ntoken after governance checks and publish evidence pass. A tag ruleset that\nprotects every `refs/tags/v*` ref is too broad because it also locks the\nfloating channel tags that Buildchain is required to update. Prefer exact-tag\npatterns such as `refs/tags/v*.*.*` for immutable release evidence, while\nleaving floating channel tags under Buildchain automation control.\n\n## Alpha Semantics\n\nAn alpha merge is:\n\n```text\ndev/vX/vX.Y -> alpha/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Computes the next prerelease for the minor line.\n2. Writes version state such as `vX.Y.Z-alpha.N`.\n3. Verifies the generated version-state tree.\n4. Creates or reuses the exact alpha tag.\n5. Moves `alpha/vX/vX.Y` to the generated alpha commit.\n6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a\n   fast-forward update.\n7. Moves `vX.Y-alpha` to the same generated alpha commit.\n8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.\n\nThe npm channel follows the same ownership rule. The highest alpha minor publishes\nwith dist-tag `alpha`; maintenance alphas on an older minor publish with the\nline-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`\nchannel backward. Exact prerelease versions remain installable directly.\n\nThis keeps the test channel self-describing. If a consumer checks out\n`v3.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major\nalpha ref removes routine consumer edits when Buildchain opens a newer minor,\nwhile exact tags and SHAs remain the reproducible audit choice.\n\n### Buildchain Alpha Self-Dogfood\n\nBuildchain continuously consumes its own current major alpha through\n`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the\nreleased channel router at `build.yml@v3-alpha`. The auto lane must resolve\n`v3-alpha`; the explicit stable lane must resolve `v3`. Both execute the same\ndeclared install, build, and verify fixture, proving that a single consumer\nsurface routes to distinct released runtimes without duplicating lifecycle\nconfiguration in the consumer.\n\nBuildchain's generic artifact-signing contract seals source-, tree-, runtime-,\nplatform-, and digest-bound requests from ordinary credential-free build jobs.\nProvider-specific authority jobs consume only those sealed payloads. Apple\nDeveloper ID, Windows Authenticode, and detached cryptographic signatures share\nthe request/receipt model, while each profile retains its honest platform\nsemantics and fail-closed verification requirements.\n\nThe authority verifies the complete result set on GitHub-hosted infrastructure\nbefore delivery. The consumer controller also performs final result verification,\nexact-byte import, manifest recomputation, and deterministic-artifact replacement\non a GitHub-hosted lane. macOS results finalize on a GitHub-hosted macOS runner so\nthe consumer lifecycle can perform native post-sign checks before publication;\nother platforms retain the GitHub-hosted Ubuntu control lane. Self-hosted build\nrunners do not download authority result payloads, and aggregate/release evidence\nfails closed until this finalization succeeds.\n\nThe central `buildchain-artifact-signing` environment reuses the established\nmacOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,\n`BUILDCHAIN_MACOS_NOTARY_API_*`, and\n`BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`). Those authority-only values are never\ndeclared by or forwarded through a consumer repository. Windows and detached\nproviders follow the same central-environment boundary.\n\nThe reusable build trust gate reads `job.workflow_ref`, which identifies the\ncalled workflow and its selected ref. It does not infer the runtime from\n`github.workflow_ref`, because GitHub defines that context as the caller\nworkflow identity during a reusable call.\n\nThe router selects `.buildchain/alpha-contract-lock.json` for alpha and\n`.buildchain/contract-lock.json` for stable. The alpha lock records the exact\nreviewed alpha SHA and compatibility digest; it does not replace the stable\nconsumer lock. A later alpha with only compatible additive drift continues,\nwhile a changed breaking digest fails until the new alpha contract is reviewed.\n\nThe evidence job resolves `v3-alpha` and `v3` through the GitHub refs API,\ncompares those immutable SHAs with the reusable workflow outputs, verifies the\n`alpha` and `stable` classifications, and uploads a JSON evidence artifact.\nThe canary runs after successful Buildchain ref promotion, on a daily fallback\nschedule, and on manual dispatch. It shares the release-promotion concurrency\ngroup, so another promotion cannot move the floating refs between runtime\nresolution and evidence comparison.\n\nThis is a post-publication consumer canary, not a release bootstrap. Source\nverification still runs the current commit, and\n`buildchain-ref-promotion.yml` still passes the verified exact SHA into the\npromotion workflow. Patrol, dev-merge, repair, and promotion defaults remain on\nstable or exact refs so a broken alpha cannot prevent Buildchain from publishing\nits fix. When Buildchain opens a new major, inventory validation requires this\nworkflow's fixed GitHub `uses` refs to move from `vN`/`vN-alpha` to the new\nmajor; GitHub does not allow expressions in a reusable-workflow `uses` ref.\n\nIf `dev/vX/vX.Y` has already advanced before generated alpha version-state\nbookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the\ndev sync and still completes the exact and floating alpha tags for the reviewed\nalpha commit. Later dev changes must go through their own dev-to-alpha\npromotion instead of rewinding dev. The normal path is direct: after alpha\nmerges, Buildchain applies the generated version-state commit to alpha and then\nfast-forwards dev to the same commit without a human version-state PR.\n\nIf alpha finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain accepts the current alpha head as the generated\ncommit, or as a historical merge commit that contains the recorded release\nmaterial. An already-created exact alpha tag may point at the transaction\nrelease/material SHA or at the finalized alpha head; missing floating alpha\ntags are retried before the transaction becomes `complete`.\n\n## Release Semantics\n\nA release merge is:\n\n```text\nalpha/vX/vX.Y -> release/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Finds the same-patch alpha tag that was tested.\n2. Checks that the release source tree matches that alpha tag tree, excluding\n   only generated version-state differences.\n3. Writes final release version state such as `vX.Y.Z`.\n4. Verifies the generated release tree.\n5. Creates or reuses the exact release tag `vX.Y.Z`.\n6. Moves `release/vX/vX.Y` to the exact release commit.\n7. Moves `vX.Y` to the exact release commit.\n8. Moves `vX` when this minor line should be the stable major entrypoint.\n9. Prepares the next alpha version-state commit, such as\n   `vX.Y.(Z+1)-alpha.0`.\n10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha\n    commit.\n11. Moves `vX-alpha` to that next alpha only when this remains the highest published alpha minor.\n\nThe historical alpha tree comparison remains the default stable source gate.\nA promote-only stable run may accept a broader reviewed release PR only when\nthe downloaded RC passport proves that the PR's exact target tree is the tree\nthat completed the PR-stage build. Buildchain also requires the target commit\nto belong to a merged same-repository PR into the selected release branch and\nrecords the accepted commit, tree, RC source, alpha source, and PR as promotion\nevidence. A stale passport, a different target tree, a generated final release\ncommit, or an unreviewed target commit still falls through to the normal\nalpha-tree and declared version-state checks.\n\nThe production channel and the test channel therefore intentionally diverge\nafter release: production stays on the release commit, while alpha/dev continue\nat the next prerelease commit.\n\n### Stable Release Throttle And Canary Gate\n\nBuildchain's own stable channel has an additional pre-publication gate. It is\nevaluated after the PR-stage release candidate has been resolved and before the\npublish-gate ref, package registry, exact stable tag, or floating stable refs\nare mutated. Train refs and alpha promotion do not execute this gate.\n\nAll alpha and release promotions first run a metadata-only release-candidate\npreflight after queued-intent revalidation. The preflight uses the same resolver\nand exact target SHA as the publication job, but does not download payloads or\ninstall the candidate repository dependencies. Missing channel PRs, stale\nworkflow runs, expired passport pairs, and insufficient payload artifact sets\ntherefore fail before the full promotion job starts. The publication job still\ndownloads and validates the exact evidence again at the trust boundary; the\npreflight moves failure earlier without weakening the final check.\n\nThe policy is versioned in `.buildchain/stable-release-policy.json`. A stable\ncandidate is allowed only when all of these facts are true:\n\n- the candidate resolves to an immutable exact alpha tag and its GitHub\n  prerelease timestamp;\n- at least 24 hours have passed since the preceding stable patch on the same\n  minor line;\n- the preceding stable-to-alpha comparison contains a product or public\n  contract path, not only version, test, evidence, or retrospective changes;\n- the version-bound impact record has a non-empty summary and at least one\n  surface impact;\n- the `Build Surface Fixture` release-candidate run succeeded;\n- `site-libkungfu-dev` completed its no-apply `Buildchain Stable Canary` and an allowed\n  maintainer attested that successful run on the exact alpha SHA through the\n  `buildchain-canary/site-libkungfu-dev` commit-status context;\n- the canary runtime input is exactly the candidate alpha tag or the 40-character\n  commit SHA resolved from that tag; a successful status pointing at another\n  workflow, repository, tag, floating ref, or SHA is rejected as mismatched;\n- at least one hour has elapsed after the last required canary completed.\n\nThe machine report is written to\n`.buildchain/release-passport/stable-release-gate.json`. A passing report is\nuploaded with the stable release passport. A blocked run writes the same report\nbefore failing, so the missing or stale condition is inspectable without\nopening a publication transaction.\n\nGitHub's Actions run REST object does not expose `workflow_dispatch` inputs.\nBuildchain therefore verifies the run's `workflow_id` against the authoritative\nworkflow metadata, then reads the exact runtime from the workflow-owned\n`<workflow name> / <runtime ref>` run-name when no input field is available.\nAn explicit API input, when present, remains authoritative and cannot be\noverridden by the display name.\n\nThe cooldown is a minimum interval, not an instruction to release every day.\nCompatible work should still be batched until a stable release has a concrete\nconsumer need. Changing the interval, canary set, attestors, product path\nboundary, or soak time is a reviewed policy change.\n\nRepositories that want a predictable scheduled stable window can use\n[`Stable Candidate Patrol`](stable-candidate-patrol.md). It persists each exact\nalpha independently, qualifies it after repository-declared checks and soak,\nand selects the newest qualified non-revoked candidate. A newer soaking alpha\ndoes not invalidate an older qualified candidate. The selected tree enters the\nexisting strict `publish-gate/release/<line>/<version> -> release/<line>` PR\npath, so scheduled selection changes release intent timing without weakening\nsource locks, review, verification, publish transactions, or passports.\n\nIf release finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain applies the same recovery rule: the current\nrelease head may be the generated commit, or a historical merge commit that\ncontains the recorded release material, existing exact tags and alpha/dev refs\nare accepted when they match the transaction, and missing floating `vX.Y` or\n`vX` tags are retried idempotently before completion.\n\nOnce the durable release transaction is `complete` and the exact/floating\nstable refs have moved, next-alpha preparation is post-release bookkeeping. A\nfailure there records `deferred-post-release-bookkeeping` and\n`next-anchor-required` instead of retroactively reporting the stable release as\nfailed. Generated next-alpha merges use the current dev tree as their base and\noverlay only declared version-state paths, preserving concurrent dev changes.\n\n## Major Gate Semantics\n\nA major gate merge is:\n\n```text\nrelease/vX/vX.Y -> publish-gate/major\n```\n\n`publish-gate/major` is the explicit replacement for the older ABV `main`\nchannel. The name is intentionally operational: it is a gate for a rare\nadministrator decision, not the active trunk. Keeping this decision in the same\nPR UI as alpha and release promotion keeps the human workflow simple while\navoiding the misleading meaning of `main`. The older `major-gate` branch name is\na compatibility alias only.\n\nBuildchain then:\n\n1. Verifies the source is a merged same-repository PR from a protected release\n   line into `publish-gate/major`.\n2. Writes the next major production version state, such as `v(X+1).0.0`.\n3. Creates or reuses the exact release tag `v(X+1).0.0`.\n4. Moves `publish-gate/major` and `release/v(X+1)/v(X+1).0` to that release commit.\n5. Moves `v(X+1).0` and `v(X+1)` to that release commit.\n6. Prepares the next alpha version-state commit, such as\n   `v(X+1).0.1-alpha.0`.\n7. Moves `alpha/v(X+1)/v(X+1).0`, `dev/v(X+1)/v(X+1).0`, and\n   `v(X+1).0-alpha` to that next alpha commit.\n\nChecking out `publish-gate/major` should therefore look like a frozen release\nstate, not like a branch where day-to-day source work continues. Day-to-day\nsource work continues on `dev/vX/vX.Y`.\n\n## Protected Dev Branches\n\n`dev/vX/vX.Y` is a protected development channel, not a scratch branch. Normal\nsource changes should be made on work branches such as `feature/*`, `fix/*`,\n`chore/*`, `docs/*`, `ci/*`, or `refactor/*`, then reviewed through a pull\nrequest into the target dev line.\n\nThis keeps the earliest development channel audit-friendly:\n\n- the version line being changed is visible in the PR base branch;\n- CI and required checks run before the channel moves;\n- branch protection can prevent direct pushes and stale merges;\n- later `dev -> alpha -> release` promotion inherits a reviewable source\n  lineage instead of trying to reconstruct how the dev branch changed.\n\nWhen required checks take longer than the normal dev-channel commit interval,\nclassic strict up-to-date protection can become a non-converging retry loop:\neach base update invalidates a completed check set and rebasing restarts the\nsame slow checks. Buildchain supports GitHub merge queues for that channel\nshape. The queue validates the projected merged result and serializes the final\nref update, so concurrent channel movement no longer invalidates the candidate.\n\nGitHub Merge Queue does not by itself decide which candidate may spend a long\nnative proof before enqueue. Repositories with that workload use the\n[Dev Delivery Warrant Queue](dev-delivery-warrant.md) as the durable,\nFIFO-aging scheduling and fencing authority before native queue admission. A\nprovisional Warrant reserves the landing order before native shards, while only\nits atomic qualified upgrade can authorize enqueue. Later candidates remain\nvisibly queued and continue source/CI work; GitHub still owns the exact\n`merge_group` proof and final ref mutation. Workflow concurrency remains only a\nprocess critical section and is not fairness or ownership authority.\n\nEvery required workflow must handle both `pull_request` and `merge_group`\nbefore the queue is enabled. Queue runs do not provide\n`github.event.pull_request`; required workflows must use the checked-out\n`github.sha` or event-neutral source facts. The governance command is dry-run by\ndefault and refuses to enable a queue when a declared required workflow lacks\neither trigger or still reads the pull-request-only payload directly:\n\n```bash\nbuildchain dev merge-queue \\\n  --repository owner/repository \\\n  --branch dev/v4/v4.0 \\\n  --workflow .github/workflows/source-acceptance.yml \\\n  --workflow .github/workflows/affected-native-pr.yml \\\n  --bypass-app dedicated-release-app\n```\n\nAfter reviewing the plan, repeat with `--apply`. Buildchain creates or updates\nan exact-branch `merge_queue` ruleset first, then changes only the classic\nrequired-status-check policy from strict to loose. Reviews, administrator\nenforcement, conversation resolution, required check identities, force-push\nprotection, and deletion protection remain owned by the existing branch\nprotection. The ruleset uses the first merge method that the repository itself\nallows, and fails closed when the repository has no enabled merge method.\nRe-running the command is idempotent.\n\nThe repository policy can be declared once instead of repeated as CLI flags:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"inherit\"\nrequired_workflows = [\".github/workflows/verify.yml\"]\n```\n\n`enabled` explicitly requires Buildchain to create or update an exact-branch\nqueue; `inherit` copies queue parameters and bypass actors from the repository's\ncurrent default dev branch; `disabled` prevents automatic queue creation. An\nabsent declaration behaves as `inherit` during release-line bootstrap so a new\nmajor or minor line does not silently lose governance already active on the\nprevious line. Required status-check identities still come from the new\nbranch's own classic protection rather than being copied from the old branch.\n\nMerge-queue rules also reject generated post-publish version-state ref updates.\nWhen the sealed promotion workflow uses a dedicated GitHub App, user, or team\nalready declared by release governance, repeat `--bypass-app`, `--bypass-user`,\nor `--bypass-team` to project that exact actor into the ruleset. Bypass actors\nare never inferred and broad repository or organization roles are not accepted.\nThis keeps ordinary feature PRs on the predecessor-aligned queue path while the\nsealed publication authority can finish its machine-verified bookkeeping. The\ndry-run receipt exposes the exact actor IDs before `--apply` changes GitHub.\n\nBuildchain provides the reusable\n`.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a\nscheduled or manual \"merge ready dev PRs\" pass. The consumer repository owns\nthe trigger schedule, but the merge decision is declared through workflow\ninputs: target dev branch, required status/check names, ready and block labels,\nallowed work-branch prefixes, review requirements, maximum merges per run,\nmerge method, and dry-run mode.\n\nAgent delivery uses the targeted Buildchain command instead of relying on a\nscheduled scan:\n\n```sh\nbuildchain dev pr-admit \\\n  --repository kungfu-systems/example \\\n  --branch dev/v3/v3.0 \\\n  --pull-request 123 \\\n  --expected-head 0123456789abcdef0123456789abcdef01234567\n```\n\nThe default is a mutation-free plan. After reviewing it, add `--execute` to\nestablish the configured readiness label for only that PR and exact head, read\nthe state back, and attempt native queue admission. Repeating execute is\nidempotent: an exact matching queue entry is adopted, not submitted again. A\nstale head or base, fork, draft, block label, missing approval, failed check,\nactive predecessor, or rejected enqueue exits nonzero. Execute mode also\ncreates or updates an exact-head PR comment and named commit status containing\nthe current state, reason, receipt root, and copyable next action. The JSON\nreceipt remains the complete content-addressed evidence.\n\nGitHub auto-merge is observed but is never readiness or admission authority.\nApproval plus green checks plus auto-merge enabled does not qualify a PR that\nlacks explicit Buildchain delivery intent. The targeted workflow interface\nexposes the same contract through `expected-pr-number` and\n`expected-head-sha`; cadence patrol runs leave those inputs empty.\n\nThe workflow defaults are conservative. A PR is skipped unless it targets the\nconfigured dev line, is not a draft, has the ready label, has no block label,\ncomes from the same repository, uses an allowed work-branch prefix, has a\ncurrent approval, is mergeable, and has the configured required checks passing.\n`landing-mode: auto` reads the target branch's native merge-queue state. When a\nqueue exists, Buildchain never calls the direct merge endpoint: it admits at\nmost one PR against the observed target-branch SHA and immutable PR head, then\ncalls GraphQL `enqueuePullRequest` with `expectedHeadOid`. GitHub's\n`merge_group` checks remain the final authority for the projected merge.\n\nThe admission receipt records the expected and observed base/head SHAs, policy\nchecks, decision, reason, and active predecessor. Buildchain re-reads the base,\nhead, mergeability, and native queue immediately before enqueueing. Base or\nhead drift fails closed, an active queue entry blocks admission, and a rejected\nready predecessor leaves its PR open while later PRs receive\n`blocked-by-predecessor`. Workflow concurrency serializes Buildchain-owned\nadmission runs; GitHub still owns the atomic queue and protected-ref update.\nRepositories may explicitly select `landing-mode: direct` only when the target\nbranch has no native queue. Queue presence always disables the direct path.\n\nFor slow candidates on a frequently advancing dev line, the optional\n[Dev Delivery Warrant Queue](dev-delivery-warrant.md) adds durable FIFO plus\naging scheduling before native queue admission. It separates reusable source\nqualification from exact merge-group integration, uses expected-old Git-ref\nupdates and fenced leases, and keeps the PR head unchanged when only dev moves.\nThe reusable caller supports `off`, read-only `shadow`, and fail-closed\n`required` rollout modes. GitHub Merge Queue remains the final protected-ref\nauthority in every mode.\n\nBounded-concurrency experiments use the separate effect-disabled Warrant\nshadow planner. It may evaluate at most two fully bound lanes from one exact\nobservation, but it cannot mint a second production Warrant or mutate GitHub.\nIts aggregate threshold decision is qualification evidence for a later rollout\nchange, not authority to change the live single-flight policy.\n\nThe canonical consumer required check context is `check / check`, matching the\nreusable workflow call plus its `check` job. Buildchain's own `Verify` workflow\nemits the repository-local context `check`, so Buildchain self-promotion,\nrelease-line bootstrap, and dogfood patrol wrappers pass `check` explicitly.\nRelease governance preserves the exact context emitted by the repository and\nrecords branch-protection policy before/after facts; it does not rewrite one\ncontext shape into the other. Consumer repositories can keep their context\nstable while changing the actual verification command declaratively in\n`buildchain.toml`:\n\nBefore a release caller is merged, consumers should also verify its exact\nreusable-workflow call contract. The checker reads the caller and an already\nchecked-out exact Buildchain commit; it never resolves a floating ref or starts\na release. It rejects unknown or missing inputs and secrets, literal type\ndrift, insufficient permissions, untrusted event classes, and a caller pin that\ndoes not equal the checked callee commit. Defaults, workflow bytes, and the\ncomplete interface are bound into `contractRoot`; the receipt additionally\nbinds the caller commit/tree and both workflow digests.\n\n```sh\nnode .buildchain/workflow-contract-runtime/scripts/workflow-call-contract.mjs check \\\n  --caller-root . \\\n  --caller-workflow .github/workflows/release-new-version.yml \\\n  --caller-repository kungfu-systems/example \\\n  --job promote \\\n  --callee-root .buildchain/workflow-contract-runtime \\\n  --callee-workflow .github/workflows/release-candidate-promote.yml \\\n  --callee-repository kungfu-systems/buildchain \\\n  --trusted-event workflow_dispatch \\\n  --trusted-event pull_request:closed \\\n  --expected-contract-root \"$(cat .buildchain/release-call-contract-root)\" \\\n  --output .buildchain/workflow-call-receipts/release-new-version.json\n```\n\nThe checkout at `.buildchain/workflow-contract-runtime` must use the same\n40-character SHA written in the caller's `uses:` edge. To accept an intentional\ncontract change, first run without `--expected-contract-root`, review the full\ndiagnostic and exact coordinates, then replace only the committed root. The\nordinary PR check runs this command before any candidate or promotion dispatch.\nLocal pre-commit rehearsal may add `--allow-dirty`; that result is marked\n`receiptReusable: false` and cannot replace the clean exact-source receipt.\n\n```toml\n[lifecycle.install]\ncommand = \"cargo fetch --locked\"\n\n[lifecycle.verify]\ncommand = \"cargo test --workspace --locked\"\n```\n\nConsumers that want Buildchain to own the check wrapper can call\n`.github/workflows/check.yml@v3`. The wrapper runs the declared\n`lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when\neither declaration is missing or the command exits non-zero.\n\nDevelopment pull requests that need source acceptance without product build or\nartifact verification can opt into `mode: source`. That mode runs only\n`lifecycle.install` and `lifecycle.check` on GitHub-hosted `ubuntu-24.04` while\npreserving the stable `check / check` required-check context. Existing callers\nremain on `mode: verify` by default, and callers may set\n`upload-artifacts: false` without weakening the job conclusion.\n\nTypical consumer wrapper:\n\n```yaml\nname: Merge Ready Dev PRs\n\non:\n  schedule:\n    - cron: \"17 * * * *\"\n  workflow_dispatch:\n    inputs:\n      dry-run:\n        type: boolean\n        default: true\n\njobs:\n  merge-dev:\n    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3\n    permissions:\n      contents: write\n      pull-requests: write\n      checks: read\n      statuses: write\n    with:\n      target-branch: dev/v3/v3.0\n      required-status-checks: check / check\n      queue-admission-context: Queue admission lease\n      ready-label: ready\n      block-labels: blocked,do-not-merge\n      max-merges: 1\n      landing-mode: auto\n      dry-run: ${{ inputs.dry-run || false }}\n```\n\nWhen the protected branch requires a merge-group-only queue lease, the wrapper\nposts that configured context as a temporary success status on the exact PR\nhead only after the ready, review, and required-check gates pass. It then\nenqueues with `expectedHeadOid`; a rejected enqueue rewrites the temporary\nstatus to failure, while the merge group must still produce its own final check.\n\n## Buildchain Patrol\n\n`dev-pr-auto-merge.yml` remains the focused merge primitive. For repositories\nthat want a stable day-to-day operations contract, Buildchain also exposes a\npatrol workflow family:\n\n| Workflow                                         | Intended cadence                   | Default intent                                                                             |\n| ------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------ |\n| `.github/workflows/patrol-daily.yml`             | daily                              | lightweight inspection plus ready dev PR maintenance                                       |\n| `.github/workflows/patrol-weekly.yml`            | weekly                             | release-state, passport, gate, and stale-state health checks as they are added             |\n| `.github/workflows/patrol-monthly.yml`           | monthly                            | governance, permission, branch-protection, and workflow drift checks as they are added     |\n| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule           | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |\n| `.github/workflows/stable-candidate-patrol.yml`  | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR                |\n\nThe cadence names describe patrol intensity, not release cadence:\n\n- daily patrol can run every day without implying a daily release;\n- weekly patrol is for medium-cost maintenance and audit checks;\n- monthly patrol is for structural drift checks that should not block ordinary\n  development velocity.\n\nEvery cadence result is typed `runKind: cadence-patrol` with\n`qualification: false`. A run with no open candidates reports\n`no-op-no-candidates`; a run where every candidate is skipped reports\n`no-op-all-skipped`. Either no-op can keep maintenance green, but neither is a\ndelivery qualification, a targeted admission receipt, or evidence that an\nexpected PR entered the merge queue.\n\nStable Candidate Patrol is separate from those maintenance cadences because its\ncaller-owned cron is a release-intent window. Its candidate ledger and selection\nremain generic; registry-specific side effects still run through the normal\nrepository `lifecycle.publish` transaction. See\n[`stable-candidate-patrol.md`](stable-candidate-patrol.md).\n\nObserved data that is mechanically regenerated and path-scoped uses the\nseparate [`Observed Evidence Patrol`](observed-evidence-patrol.md) contract.\nIts one-time mechanism changes remain reviewed, while steady-state snapshot\nrefreshes publish directly from trusted default-branch schedule/manual callers.\n\nConsumers should schedule thin callers and keep their YAML declarative. For\nexample:\n\n```yaml\nname: Buildchain Daily Patrol\n\non:\n  schedule:\n    - cron: \"17 2 * * *\"\n  workflow_dispatch:\n\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v3\n    with:\n      dry-run: false\n      max-actions: 1\n```\n\nWeekly and monthly callers use the matching wrapper:\n\n```yaml\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v3\n    with:\n      dry-run: true\n```\n\nAll three wrappers default to the `v3` floating Buildchain runtime. When\n`target-branch` is omitted, the caller's current/default branch selects the\nactive semver dev line, so consumers do not pin patrol to a stale minor branch.\nThe separate workflow names keep consumer schedules readable and stable while\nBuildchain adds new checks behind the cadence wrappers.\n\nBranch and pull-request residue uses the separate\n[`Engineering Housekeeper`](engineering-housekeeper.md) contract. Its reusable\nsurface remains report-first, while Buildchain's committed daily, weekly, and\nmonthly callers run unattended apply across all discovered protected mainlines.\nOnly the positive temporary-development allowlist is mutable; unknown branch\nfamilies remain report-only. Every apply still requires the caller's explicit\ntwo-part policy inputs, exact provider-state revalidation, scoped job\npermissions, and rooted plan/report/receipt evidence.\n\n## Package-Manager Adapters\n\nOld ABV assumed JavaScript repositories with root version state and often\nLerna. Buildchain keeps the version-state contract but does not assume every\nrepository is yarn/Lerna.\n\nThe promotion action discovers and updates:\n\n- root `package.json`;\n- `lerna.json`;\n- package manifests from `package.json` workspaces;\n- package manifests from `lerna.json` packages;\n- package manifests from `pnpm-workspace.yaml`.\n\nIt then runs the repository's detected package manager semantics where needed:\n\n- pnpm repositories use pnpm-oriented workspace discovery;\n- npm repositories use npm/package-lock semantics where present;\n- yarn repositories use yarn-style metadata where present.\n\nFor Buildchain itself, version state is required. For a consumer repository that\nhas no package manifest, the same action can degrade to ref-only behavior only\nwhen that is explicitly allowed by the caller.\n\n## Lifecycle Configuration\n\n`.buildchain/buildchain.toml` is the v3 user configuration format. It lets a repository\ndeclare version-state files and lifecycle commands without pretending every\nproject is a Node workspace. Supported version files include JSON, TOML, and\nregex-based files such as `CMakeLists.txt` or `conanfile.py`.\n\nThe promotion action consumes `version.files`, optional\n`version.derived_files`, and `lifecycle.verify`. Semver and anchored/manual\nrepositories may both declare lifecycle-regenerated tracked outputs as derived\nfiles; anchored/manual repositories additionally bind them into their committed\nversion witnesses.\nThe verify stage runs after generated version-state changes are applied locally\nand before any release refs move. If `verification-command` is passed directly\nto the action, that explicit command overrides `lifecycle.verify`.\n\nAnchored/manual repositories may use `version.derived_files` for committed\nversion witnesses that are regenerated by `lifecycle.version-state`. The\nrelease-candidate build verifies those witnesses before heavy builds and records\ntheir digests with the exact alpha and release tree identities. Promotion then\naccepts only declared version files, the anchor manifest, and those derived\nfiles as differences from the tested alpha tree; release passports preserve the\nsame material binding.\n\nProtected release-line branches keep their normal human review gate. Managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured\nwith one required approving review, required GitHub Actions checks, administrator\nenforcement, conversation resolution, no force pushes, and no deletions. Each\ntarget uses the exact check set, GitHub App identity, and strictness declared by\nthe governance authority descriptor. The\nreusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, which lets the workflow's\nautomation identity apply generated version-state or post-publish channel\nbookkeeping after the reviewed channel PR has merged. Direct\n`promote-buildchain-ref` callers may opt into that one controlled bypass with\n`branch-protection-bypass-apps: github-actions`; every other App slug and all\nuser or team bypass actors are rejected. Before\npatching a protected generated bookkeeping ref, the action creates the\nfull configured required-check set on the exact generated version-state commit, so strict\nstatus checks are satisfied by machine-verifiable Buildchain evidence rather\nthan a human PR. The protected ref PATCH itself uses the generated ref update\ntoken; the reusable wrapper binds it to the run-scoped `github.token`. If direct generated\nrelease finalization bookkeeping is still rejected, Buildchain creates or\nreuses a same-repository `buildchain/version-state/*` PR and records\n`finalization-needed=true` in the durable transaction output. Strict alpha\nfollows the same provider-enforced PR path for its alpha and dev bookkeeping.\nThe PR remains subject to the declared review, required checks, and merge-queue\npolicy; publication resumes idempotently after that protected transaction\nlands.\n\nFor a stable release, the wrapper also checks out the exact current development\nchannel into `.buildchain/reconciliation/dev`. When the prepared next-alpha\ncommit cannot fast-forward dev because reviewed work landed concurrently, the\npromotion action applies the next version to that checkout, regenerates every\ndeclared derived version-state file, reruns the verification lifecycle, and\nonly then creates the two-parent reconciliation commit. A checkout/current-ref\nSHA mismatch blocks reconciliation instead of committing stale projections.\nBuildchain's own promotion workflow accepts only\n`BUILDCHAIN_PROMOTION_BYPASS_APPS=github-actions`, defaulting to that exact App\nwhen the variable is absent. Buildchain's release-line bootstrap uses the\nadministrator-scoped promotion token only to configure protection; branch\ncreation and generated ref updates use the run-scoped token. New channel\nprotection binds required checks to GitHub Actions App id `15368`, enables Code\nOwner, stale-review, and latest-push review gates, and admits no user or team\nbypass actor.\n\n## What This Guarantees\n\nWhen the loop succeeds, maintainers and consumers can rely on these facts:\n\n- every production release has an exact tag such as `v3.0.2`;\n- every production minor line has a floating tag such as `v3.0`;\n- every selected stable major has a floating tag such as `v3`;\n- every next-major release is driven by a reviewed `release -> publish-gate/major` PR,\n  not a hidden manual button;\n- every test channel has an exact alpha tag such as `v3.0.3-alpha.0`;\n- every alpha minor line has a floating tag such as `v3.0-alpha`;\n- every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;\n- version manifests match the tag visible from the same commit;\n- production releases are derived from the alpha tree that was tested;\n- manual non-dry-run promotion cannot bypass PR review and verification;\n- flow-internal automation bypasses apply only to declared GitHub Apps, users,\n  or teams on Buildchain-managed channel branch protection, while one-review\n  protection remains enforced for humans;\n- admin users cannot make a channel promotion valid by temporarily bypassing\n  branch protection.\n\nThis is the practical meaning of \"governance closed loop\" in Buildchain: the\ndecision, code, version state, and Git refs close over the same evidence chain.\n\n## What This Does Not Do\n\nBuildchain release promotion does not embed registry clients or product-specific\npublish logic. When publish transactions are enabled, `promote-buildchain-ref`\ncan run the consumer's `lifecycle.publish` command and own the transaction,\nevidence validation, durable recovery state, and ref finalization order. The\nconsumer repository still owns registry truth: npm, PyPI, OCI, S3, Conan, CMake\npackaging, download pages, dist-tags, and similar side effects must be\nimplemented by project lifecycle commands that emit Buildchain publish evidence.\n\nDurable transaction recovery is also bound to the exact publication version\nplanned for the current run. An unfinished transaction may be resumed from the\ncurrent source or its history only when its recorded version matches that plan;\nan older failed transaction that happens to be an ancestor cannot reserve its\nold exact tag for a newer package publication.\n\nThe exact tag is also part of the durable transaction identity. If an anchored\npackage publication completed registry side effects under a stale internal tag\nselection, a retry may rebind the unfinished `published` or `finalizing`\ntransaction to the newly planned internal tag only when the package version,\nsource, release material, target, complete artifact set, and evidence all still\nmatch; the stale tag must not point at the transaction, and the requested tag\nmust be absent or already point at accepted release material. This preserves an\nimmutable tag that represents a completed transaction while allowing a tag\ncollision discovered after registry publication to recover without republishing.\n\nFor package publish transactions, the immutable public version tag points to\nthe transaction `source_sha`, so registry source metadata such as npm `gitHead`\nand the Git tag identify the same source commit. Protected branches and mutable\nchannel tags continue to point to the generated `release_sha`. Recovery accepts\nolder completed transactions whose exact tags already point to recorded release\nor release-material SHAs, but new tags are source-bound.\n\nEvery Buildchain publish model that can run registry side effects must bind the\npublish entrypoint to an immutable `publish-gate/*` source lock. The reusable\n`release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and\npasses `require-publish-source-lock`, `publish-source-ref`,\n`publish-source-sha`, and `publish-source-locked` to\n`promote-buildchain-ref`. Direct action callers must pass the same four inputs\nfrom the reusable build outputs. Workflows that only collect passports or run\ndry-run package checks do not move publish refs and are not publish-gate\npublication models. A dry-run of `release-candidate-promote.yml` computes and\nreports the exact `publish-gate/*` source lock that a real promotion would use,\nbut does not read, create, or move that ref.\n\nSemver GitHub Release publication is owned by `promote-buildchain-ref`, not by\nconsumer shell glue. Consumers normally use the `release-candidate-promote.yml`\ngenerated channel router, where GitHub Release publication is enabled by default and can be\ndisabled with `github-release: false`; the wrapper passes that declaration to\nthe action. After the publish transaction reaches `complete`, Buildchain creates\nor updates the public GitHub Release and uploads the generated\n`buildchain.release.json`, release-passport assets, and publish evidence. The\nauthoritative publication channel controls GitHub metadata: alpha is marked\n`prerelease=true` and `make_latest=false`; release/stable/major is marked latest.\nSemver tag syntax remains the fallback for ordinary callers without explicit\npublication intent. For anchored/manual package releases, the public\nrelease tag defaults to `v<publishedVersion>` while the internal exact\ntransaction tag remains in the release passport and release-state ref. This is\nthe supported path for downstream\n`release.published` propagation across semver, major, and promote-only release\ncandidate publication models.\n\nPublished GitHub Release assets are immutable evidence. A repeated promotion\npreserves an existing asset when its SHA-256 digest matches the regenerated\nbytes, uploads only missing assets, and fails with an immutable-release\ncollision when a same-name asset has different bytes. It never deletes and\nreplaces an existing asset during retry or duplicate workflow delivery.\nAn explicit candidate recovery whose validated receipt records an already\ncomplete transaction instead verifies the existing public Release Passport\nbundle and preserves its Buildchain-owned evidence generation. Product payload\nbytes remain digest-bound to the restored candidate, and missing product assets\nalone may be filled from that sealed bundle. This exception is unavailable to\nordinary reruns or receipts from earlier transaction states.\n\nProduct payloads are included only through the explicit\n`github-release-payload-patterns` input. Patterns match basenames inside the\ndownloaded PR-stage RC payload bundle; zero matches or duplicate public\nbasenames fail closed. This preserves the exact PR-built bytes instead of\nrebuilding archives during promotion.\n\nConsumers with a signed well-known discovery document can additionally provide\n`publication-commit-command`. The advanced promotion workflow validates its\ntopology before any publish-gate or release mutation, then runs it only after\nthe GitHub Release and its immutable payload/passport assets exist. The command\nmust publicly read back the exact new payload root and emit\n`kungfu-buildchain-publication-commit-evidence/v1`; that evidence is copied\ninto the controller artifact and exposed as workflow outputs. The previous\nauthority must remain valid on every failure. Deferred standalone binary\ndistribution is incompatible with this mode because the discovery authority\nmust be the final product mutation.\n\nBuildchain also does not maintain bare exact tags such as `1.0.0`. The supported\nexact release and alpha refs are v-prefixed:\n\n```text\nv3.0.0\nv3.0.1-alpha.0\n```\n\n## Operational Reading Order\n\nWhen debugging or extending release behavior, read in this order:\n\n1. `docs/release-flow.md`\n2. `.github/workflows/release-verify.yml`\n3. `.github/workflows/buildchain-ref-promotion.yml`\n4. `.github/workflows/release-candidate-promote.yml`\n5. `.github/workflows/.release-candidate-promote.yml`\n6. `actions/promote-buildchain-ref/README.md`\n7. `actions/promote-buildchain-ref/src/`\n8. `docs/migration-inventory.md`\n\nThat path gives the policy first, the workflow trigger second, and the action\nimplementation last."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-release-governance\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  invisible_context: not asserted\n---\n\n# Release Governance\n\nBuildchain v3 preserves the release semantics of the older ABV workflow while\nmoving the implementation into one modern repository.\n\nThe central idea is simple: a reviewed merge into a release channel is the\nrelease intent. Automation must then create the version-state commit, exact tag,\nfloating tag, and next alpha state that make that intent true in Git.\n\n## Design Problem\n\nKungfu release automation has to keep four facts aligned:\n\n1. The source tree that was reviewed.\n2. The package version recorded in manifests such as `package.json` or\n   `lerna.json`.\n3. The exact immutable release or prerelease tag.\n4. The floating channel refs that consumers actually use.\n\nIf any one of these facts is updated by hand, the system can split:\n\n- a consumer can fetch `v3.0` and receive a tree whose package version still\n  says the previous release;\n- a maintainer can move `v3` without producing an exact `v3.0.N` audit tag;\n- an alpha can be promoted to production even though the release tree is not the\n  same tree that was tested;\n- a protected branch merge can succeed while the follow-up version commit is\n  missing, or a flow-internal generated `dev`/`alpha`/`release` ref update can\n  fail after publish because the automation identity was not declared in the\n  branch-protection review bypass allowance.\n\nThe older ABV workflow addressed this by letting GitHub PRs drive release\nstate. Buildchain keeps that choice because it makes release intent reviewable,\nobservable, and recoverable from Git history.\n\n## What ABV Contributed\n\nThe old ABV model was not just \"bump a version number.\" It encoded a governance\nloop:\n\n- release branches are named as channels: `dev`, `alpha`, `release`, and the\n  administrative `publish-gate/major`;\n- a PR from one channel to the next is the release request;\n- verify jobs check that the branch pair is valid before merge;\n- a maintainer review is required before the branch moves;\n- after merge, automation writes the version change and moves tags;\n- exact tags and floating refs are aligned with the resulting commit;\n- the next development channel is prepared automatically.\n\nABV also kept the version-state mutation in the repository. For JavaScript\nrepositories that usually meant changing `lerna.json` and/or `package.json`.\nThat commit is important because the tag alone is not enough evidence: the\nsource tree should also declare the version that the tag advertises.\n\nBuildchain v3 treats that as a hard semantic requirement for its own release\nline.\n\n## Buildchain Implementation\n\nBuildchain implements the same governance loop with:\n\n- `.github/workflows/release-verify.yml` for PR verification;\n- `.github/workflows/buildchain-ref-promotion.yml` for post-verify ref\n  promotion; this workflow dogfoods the declarative\n  `release-candidate-promote.yml` wrapper and does not hand-wire resolver,\n  artifact download, publish-gate, or promote action steps;\n- Buildchain self promotion enables `release-passport-buildchain-self-kfd`, so\n  the promote action generates KFD-1 witnesses, KFD-2 public claim JSON, and\n  KFD-3 collaboration-interface witnesses from the final version-state workspace\n  before release passport finalization. The witness hashes therefore bind to the\n  exact published package and site facts from\n  `packages/core/buildchain-kfd-claims.js` instead of relying on prose release\n  notes;\n- `actions/promote-buildchain-ref` for branch, tag, version-state, and\n  governance checks;\n- package-manager adapters that can update version state for pnpm, npm, and\n  yarn style repositories;\n- `buildchain.toml` lifecycle configuration for repositories whose version\n  state or verification commands are not Node package-manager defaults.\n\nThe implementation is intentionally stricter than a local release script:\n\n- manual workflow dispatch can only do dry-run promotion;\n- non-dry-run promotion must be driven by a completed `Verify` workflow;\n- target branch protection details must be readable, and branch protection must\n  apply to administrators as well as regular contributors;\n- `alpha/vX/vX.Y` and `release/vX/vX.Y` branch protection must require both the\n  general `check` context and the Release Verify aggregate `verify` context, so\n  an invalid channel pair cannot merge even when repository checks pass;\n- release targets keep those checks non-strict with respect to source-branch\n  ancestry: generated channel bookkeeping intentionally makes the source and\n  target histories diverge, while the pair-specific `verify` context validates\n  the legal channel transition;\n- alpha promotion must come from a merged same-repository PR from\n  `dev/vX/vX.Y` to `alpha/vX/vX.Y`;\n- release promotion must come from a merged same-repository PR from\n  `alpha/vX/vX.Y` to `release/vX/vX.Y`;\n- an exact SHA that is itself the merge commit of a reviewed same-repository PR\n  into the protected target is equivalent lineage evidence; a commit merely\n  contained by an unrelated PR is not;\n- major promotion must come from a merged same-repository PR from\n  `release/vX/vX.Y` to `publish-gate/major`;\n- release promotion requires an existing same-patch alpha tag and checks the\n  release source tree against that tested alpha tree;\n- generated version-state commits are verified before refs move.\n\n## Reconciling a protected line without rebuilding\n\nThe public `build.yml` channel router ends with a top-level job named\n`Summarize build contract`. Keeping this aggregate at the public router boundary\nprevents its required check context from changing when the internal reusable\nbuild workflow gains another nesting layer.\n\nFor an already-tested pull request whose protected target still requires an\nolder Buildchain aggregate context, inspect the exact candidate SHA first:\n\n```bash\nGH_TOKEN=\"$(gh auth token)\" npx @kungfu-tech/buildchain@latest \\\n  release-governance reconcile \\\n  --repository kungfu-systems/example \\\n  --branch release/v3/v3.0 \\\n  --candidate-sha <tested-pr-head-sha> \\\n  --json\n```\n\nThe dry run reads the successful checks emitted for that SHA and reports the\nexact expected/actual context pair. It chooses the shallowest successful\n`Summarize build contract` context, so a new top-level router aggregate wins\nover the nested internal build summary. To apply the plan, rerun the same\ncommand with `--apply` using a token that can update branch protection.\n\nReconciliation changes only the required-status-check subresource. It replaces\nstale Buildchain aggregate contexts, preserves unrelated checks and strictness,\nand does not modify review requirements, administrator enforcement,\nconversation resolution, force-push policy, or deletion policy. The candidate\nmust still be the head of a pull request targeting the named managed branch;\nthe command fails closed otherwise. This lets a previously successful candidate\ncontinue from the same SHA without another native build or an administrator\nmerge bypass.\n\nRepositories may also expose a small caller workflow around\n`.github/workflows/release-governance-reconcile.yml@v3`. Pass `branch`,\n`candidate-sha`, and `apply`, and provide `governance-token` through the caller's\nsecrets. The reusable workflow uploads the JSON reconciliation receipt.\n\nExact publication planning installs the checked-out promotion source's declared\ndependencies before version-state verification. This keeps the pre-authority\nversion plan on the same package-manager boundary as the later promotion job,\nincluding repositories whose verification commands import production packages.\nThe planning pass may materialize and verify declared derived files locally,\nbut dry-run never creates Git blobs, trees, commits, refs, or tags.\n\nPromotion intents are serialized globally per caller repository with\n`cancel-in-progress: false`. A queued intent re-reads its protected target ref\nbefore checkout, dependency installation, release-candidate resolution, or any\npublish-gate/ref mutation. If the ref already points at a newer SHA, that older\nintent is no longer release authority: the workflow records the requested and\ncurrent SHAs, proves that the current target is ahead of the requested commit,\nand completes as a `target-ref-advanced` superseded no-op. Diverged or behind\ncomparisons are not superseded transactions and still fail closed.\nMissing refs, unreadable repository state, invalid channels, governance\nfailures, and artifact mismatches still fail closed. The promote action repeats\nthe target check at the mutation boundary, so a ref that advances after the\nworkflow preflight cannot receive a second set of publication side effects.\n\n## Version Lines\n\nKungfu uses Python-like version lines where a minor line can represent a\nlong-lived product train. A line such as `v3.0` can produce many production\npatch releases:\n\n```text\nv3.0.0\nv3.0.1\nv3.0.2\n...\nv3.0.1234\n```\n\nThis is why Buildchain maintains both exact and floating refs:\n\n- `v3.0.2` is immutable release evidence;\n- `v3.0` is the latest production release on the `3.0` line;\n- `v3` is the selected stable major-line entrypoint;\n- `v3.0.3-alpha.0` is immutable alpha evidence;\n- `v3.0-alpha` is the latest test channel for the `3.0` line.\n- `v3-alpha` is the latest test channel on the highest published alpha minor in major `3`.\n\nA release does not mean \"minor is complete.\" It means \"this patch on this minor\nline is now production.\"\n\nGitHub repository rules must preserve that distinction. Exact tags such as\n`v3.0.2` and `v3.0.3-alpha.0` should be immutable. Floating channel tags such as\n`v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion\ntoken after governance checks and publish evidence pass. A tag ruleset that\nprotects every `refs/tags/v*` ref is too broad because it also locks the\nfloating channel tags that Buildchain is required to update. Prefer exact-tag\npatterns such as `refs/tags/v*.*.*` for immutable release evidence, while\nleaving floating channel tags under Buildchain automation control.\n\n## Alpha Semantics\n\nAn alpha merge is:\n\n```text\ndev/vX/vX.Y -> alpha/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Computes the next prerelease for the minor line.\n2. Writes version state such as `vX.Y.Z-alpha.N`.\n3. Verifies the generated version-state tree.\n4. Creates or reuses the exact alpha tag.\n5. Moves `alpha/vX/vX.Y` to the generated alpha commit.\n6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a\n   fast-forward update.\n7. Moves `vX.Y-alpha` to the same generated alpha commit.\n8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.\n\nThe npm channel follows the same ownership rule. The highest alpha minor publishes\nwith dist-tag `alpha`; maintenance alphas on an older minor publish with the\nline-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`\nchannel backward. Exact prerelease versions remain installable directly.\n\nThis keeps the test channel self-describing. If a consumer checks out\n`v3.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major\nalpha ref removes routine consumer edits when Buildchain opens a newer minor,\nwhile exact tags and SHAs remain the reproducible audit choice.\n\n### Buildchain Alpha Self-Dogfood\n\nBuildchain continuously consumes its own current major alpha through\n`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the\nreleased channel router at `build.yml@v3-alpha`. The auto lane must resolve\n`v3-alpha`; the explicit stable lane must resolve `v3`. Both execute the same\ndeclared install, build, and verify fixture, proving that a single consumer\nsurface routes to distinct released runtimes without duplicating lifecycle\nconfiguration in the consumer.\n\nBuildchain's generic artifact-signing contract seals source-, tree-, runtime-,\nplatform-, and digest-bound requests from ordinary credential-free build jobs.\nProvider-specific authority jobs consume only those sealed payloads. Apple\nDeveloper ID, Windows Authenticode, and detached cryptographic signatures share\nthe request/receipt model, while each profile retains its honest platform\nsemantics and fail-closed verification requirements.\n\nThe authority verifies the complete result set on GitHub-hosted infrastructure\nbefore delivery. The consumer controller also performs final result verification,\nexact-byte import, manifest recomputation, and deterministic-artifact replacement\non a GitHub-hosted lane. macOS results finalize on a GitHub-hosted macOS runner so\nthe consumer lifecycle can perform native post-sign checks before publication;\nother platforms retain the GitHub-hosted Ubuntu control lane. Self-hosted build\nrunners do not download authority result payloads, and aggregate/release evidence\nfails closed until this finalization succeeds.\n\nThe central `buildchain-artifact-signing` environment reuses the established\nmacOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,\n`BUILDCHAIN_MACOS_NOTARY_API_*`, and\n`BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`). Those authority-only values are never\ndeclared by or forwarded through a consumer repository. Windows and detached\nproviders follow the same central-environment boundary.\n\nThe reusable build trust gate reads `job.workflow_ref`, which identifies the\ncalled workflow and its selected ref. It does not infer the runtime from\n`github.workflow_ref`, because GitHub defines that context as the caller\nworkflow identity during a reusable call.\n\nThe router selects `.buildchain/alpha-contract-lock.json` for alpha and\n`.buildchain/contract-lock.json` for stable. The alpha lock records the exact\nreviewed alpha SHA and compatibility digest; it does not replace the stable\nconsumer lock. A later alpha with only compatible additive drift continues,\nwhile a changed breaking digest fails until the new alpha contract is reviewed.\n\nThe evidence job resolves `v3-alpha` and `v3` through the GitHub refs API,\ncompares those immutable SHAs with the reusable workflow outputs, verifies the\n`alpha` and `stable` classifications, and uploads a JSON evidence artifact.\nThe canary runs after successful Buildchain ref promotion, on a daily fallback\nschedule, and on manual dispatch. It shares the release-promotion concurrency\ngroup, so another promotion cannot move the floating refs between runtime\nresolution and evidence comparison.\n\nThis is a post-publication consumer canary, not a release bootstrap. Source\nverification still runs the current commit, and\n`buildchain-ref-promotion.yml` still passes the verified exact SHA into the\npromotion workflow. Patrol, dev-merge, repair, and promotion defaults remain on\nstable or exact refs so a broken alpha cannot prevent Buildchain from publishing\nits fix. When Buildchain opens a new major, inventory validation requires this\nworkflow's fixed GitHub `uses` refs to move from `vN`/`vN-alpha` to the new\nmajor; GitHub does not allow expressions in a reusable-workflow `uses` ref.\n\nIf `dev/vX/vX.Y` has already advanced before generated alpha version-state\nbookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the\ndev sync and still completes the exact and floating alpha tags for the reviewed\nalpha commit. Later dev changes must go through their own dev-to-alpha\npromotion instead of rewinding dev. The normal path is direct: after alpha\nmerges, Buildchain applies the generated version-state commit to alpha and then\nfast-forwards dev to the same commit without a human version-state PR.\n\nIf alpha finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain accepts the current alpha head as the generated\ncommit, or as a historical merge commit that contains the recorded release\nmaterial. An already-created exact alpha tag may point at the transaction\nrelease/material SHA or at the finalized alpha head; missing floating alpha\ntags are retried before the transaction becomes `complete`.\n\n## Release Semantics\n\nA release merge is:\n\n```text\nalpha/vX/vX.Y -> release/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Finds the same-patch alpha tag that was tested.\n2. Checks that the release source tree matches that alpha tag tree, excluding\n   only generated version-state differences.\n3. Writes final release version state such as `vX.Y.Z`.\n4. Verifies the generated release tree.\n5. Creates or reuses the exact release tag `vX.Y.Z`.\n6. Moves `release/vX/vX.Y` to the exact release commit.\n7. Moves `vX.Y` to the exact release commit.\n8. Moves `vX` when this minor line should be the stable major entrypoint.\n9. Prepares the next alpha version-state commit, such as\n   `vX.Y.(Z+1)-alpha.0`.\n10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha\n    commit.\n11. Moves `vX-alpha` to that next alpha only when this remains the highest published alpha minor.\n\nThe historical alpha tree comparison remains the default stable source gate.\nA promote-only stable run may accept a broader reviewed release PR only when\nthe downloaded RC passport proves that the PR's exact target tree is the tree\nthat completed the PR-stage build. Buildchain also requires the target commit\nto belong to a merged same-repository PR into the selected release branch and\nrecords the accepted commit, tree, RC source, alpha source, and PR as promotion\nevidence. A stale passport, a different target tree, a generated final release\ncommit, or an unreviewed target commit still falls through to the normal\nalpha-tree and declared version-state checks.\n\nThe production channel and the test channel therefore intentionally diverge\nafter release: production stays on the release commit, while alpha/dev continue\nat the next prerelease commit.\n\n### Stable Release Throttle And Canary Gate\n\nBuildchain's own stable channel has an additional pre-publication gate. It is\nevaluated after the PR-stage release candidate has been resolved and before the\npublish-gate ref, package registry, exact stable tag, or floating stable refs\nare mutated. Train refs and alpha promotion do not execute this gate.\n\nAll alpha and release promotions first run a metadata-only release-candidate\npreflight after queued-intent revalidation. The preflight uses the same resolver\nand exact target SHA as the publication job, but does not download payloads or\ninstall the candidate repository dependencies. Missing channel PRs, stale\nworkflow runs, expired passport pairs, and insufficient payload artifact sets\ntherefore fail before the full promotion job starts. The publication job still\ndownloads and validates the exact evidence again at the trust boundary; the\npreflight moves failure earlier without weakening the final check.\n\nThe policy is versioned in `.buildchain/stable-release-policy.json`. A stable\ncandidate is allowed only when all of these facts are true:\n\n- the candidate resolves to an immutable exact alpha tag and its GitHub\n  prerelease timestamp;\n- at least 24 hours have passed since the preceding stable patch on the same\n  minor line;\n- the preceding stable-to-alpha comparison contains a product or public\n  contract path, not only version, test, evidence, or retrospective changes;\n- the version-bound impact record has a non-empty summary and at least one\n  surface impact;\n- the `Build Surface Fixture` release-candidate run succeeded;\n- `site-libkungfu-dev` completed its no-apply `Buildchain Stable Canary` and an allowed\n  maintainer attested that successful run on the exact alpha SHA through the\n  `buildchain-canary/site-libkungfu-dev` commit-status context;\n- the canary runtime input is exactly the candidate alpha tag or the 40-character\n  commit SHA resolved from that tag; a successful status pointing at another\n  workflow, repository, tag, floating ref, or SHA is rejected as mismatched;\n- at least one hour has elapsed after the last required canary completed.\n\nThe machine report is written to\n`.buildchain/release-passport/stable-release-gate.json`. A passing report is\nuploaded with the stable release passport. A blocked run writes the same report\nbefore failing, so the missing or stale condition is inspectable without\nopening a publication transaction.\n\nGitHub's Actions run REST object does not expose `workflow_dispatch` inputs.\nBuildchain therefore verifies the run's `workflow_id` against the authoritative\nworkflow metadata, then reads the exact runtime from the workflow-owned\n`<workflow name> / <runtime ref>` run-name when no input field is available.\nAn explicit API input, when present, remains authoritative and cannot be\noverridden by the display name.\n\nThe cooldown is a minimum interval, not an instruction to release every day.\nCompatible work should still be batched until a stable release has a concrete\nconsumer need. Changing the interval, canary set, attestors, product path\nboundary, or soak time is a reviewed policy change.\n\nRepositories that want a predictable scheduled stable window can use\n[`Stable Candidate Patrol`](stable-candidate-patrol.md). It persists each exact\nalpha independently, qualifies it after repository-declared checks and soak,\nand selects the newest qualified non-revoked candidate. A newer soaking alpha\ndoes not invalidate an older qualified candidate. The selected tree enters the\nexisting strict `publish-gate/release/<line>/<version> -> release/<line>` PR\npath, so scheduled selection changes release intent timing without weakening\nsource locks, review, verification, publish transactions, or passports.\n\nIf release finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain applies the same recovery rule: the current\nrelease head may be the generated commit, or a historical merge commit that\ncontains the recorded release material, existing exact tags and alpha/dev refs\nare accepted when they match the transaction, and missing floating `vX.Y` or\n`vX` tags are retried idempotently before completion.\n\nOnce the durable release transaction is `complete` and the exact/floating\nstable refs have moved, next-alpha preparation is post-release bookkeeping. A\nfailure there records `deferred-post-release-bookkeeping` and\n`next-anchor-required` instead of retroactively reporting the stable release as\nfailed. Generated next-alpha merges use the current dev tree as their base and\noverlay only declared version-state paths, preserving concurrent dev changes.\n\n## Major Gate Semantics\n\nA major gate merge is:\n\n```text\nrelease/vX/vX.Y -> publish-gate/major\n```\n\n`publish-gate/major` is the explicit replacement for the older ABV `main`\nchannel. The name is intentionally operational: it is a gate for a rare\nadministrator decision, not the active trunk. Keeping this decision in the same\nPR UI as alpha and release promotion keeps the human workflow simple while\navoiding the misleading meaning of `main`. The older `major-gate` branch name is\na compatibility alias only.\n\nBuildchain then:\n\n1. Verifies the source is a merged same-repository PR from a protected release\n   line into `publish-gate/major`.\n2. Writes the next major production version state, such as `v(X+1).0.0`.\n3. Creates or reuses the exact release tag `v(X+1).0.0`.\n4. Moves `publish-gate/major` and `release/v(X+1)/v(X+1).0` to that release commit.\n5. Moves `v(X+1).0` and `v(X+1)` to that release commit.\n6. Prepares the next alpha version-state commit, such as\n   `v(X+1).0.1-alpha.0`.\n7. Moves `alpha/v(X+1)/v(X+1).0`, `dev/v(X+1)/v(X+1).0`, and\n   `v(X+1).0-alpha` to that next alpha commit.\n\nChecking out `publish-gate/major` should therefore look like a frozen release\nstate, not like a branch where day-to-day source work continues. Day-to-day\nsource work continues on `dev/vX/vX.Y`.\n\n## Protected Dev Branches\n\n`dev/vX/vX.Y` is a protected development channel, not a scratch branch. Normal\nsource changes should be made on work branches such as `feature/*`, `fix/*`,\n`chore/*`, `docs/*`, `ci/*`, or `refactor/*`, then reviewed through a pull\nrequest into the target dev line.\n\nThis keeps the earliest development channel audit-friendly:\n\n- the version line being changed is visible in the PR base branch;\n- CI and required checks run before the channel moves;\n- branch protection can prevent direct pushes and stale merges;\n- later `dev -> alpha -> release` promotion inherits a reviewable source\n  lineage instead of trying to reconstruct how the dev branch changed.\n\nWhen required checks take longer than the normal dev-channel commit interval,\nclassic strict up-to-date protection can become a non-converging retry loop:\neach base update invalidates a completed check set and rebasing restarts the\nsame slow checks. Buildchain supports GitHub merge queues for that channel\nshape. The queue validates the projected merged result and serializes the final\nref update, so concurrent channel movement no longer invalidates the candidate.\n\nGitHub Merge Queue does not by itself decide which candidate may spend a long\nnative proof before enqueue. Repositories with that workload use the\n[Dev Delivery Warrant Queue](dev-delivery-warrant.md) as the durable,\nFIFO-aging scheduling and fencing authority before native queue admission. A\nprovisional Warrant reserves the landing order before native shards, while only\nits atomic qualified upgrade can authorize enqueue. Later candidates remain\nvisibly queued and continue source/CI work; GitHub still owns the exact\n`merge_group` proof and final ref mutation. Workflow concurrency remains only a\nprocess critical section and is not fairness or ownership authority.\n\nEvery required workflow must handle both `pull_request` and `merge_group`\nbefore the queue is enabled. Queue runs do not provide\n`github.event.pull_request`; required workflows must use the checked-out\n`github.sha` or event-neutral source facts. The governance command is dry-run by\ndefault and refuses to enable a queue when a declared required workflow lacks\neither trigger or still reads the pull-request-only payload directly:\n\n```bash\nbuildchain dev merge-queue \\\n  --repository owner/repository \\\n  --branch dev/v4/v4.0 \\\n  --workflow .github/workflows/source-acceptance.yml \\\n  --workflow .github/workflows/affected-native-pr.yml \\\n  --bypass-app dedicated-release-app\n```\n\nAfter reviewing the plan, repeat with `--apply`. Buildchain creates or updates\nan exact-branch `merge_queue` ruleset first, then changes only the classic\nrequired-status-check policy from strict to loose. Reviews, administrator\nenforcement, conversation resolution, required check identities, force-push\nprotection, and deletion protection remain owned by the existing branch\nprotection. The ruleset uses the first merge method that the repository itself\nallows, and fails closed when the repository has no enabled merge method.\nRe-running the command is idempotent.\n\nThe repository policy can be declared once instead of repeated as CLI flags:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"inherit\"\nrequired_workflows = [\".github/workflows/verify.yml\"]\n```\n\n`enabled` explicitly requires Buildchain to create or update an exact-branch\nqueue; `inherit` copies queue parameters and bypass actors from the repository's\ncurrent default dev branch; `disabled` prevents automatic queue creation. An\nabsent declaration behaves as `inherit` during release-line bootstrap so a new\nmajor or minor line does not silently lose governance already active on the\nprevious line. Required status-check identities still come from the new\nbranch's own classic protection rather than being copied from the old branch.\n\nMerge-queue rules also reject generated post-publish version-state ref updates.\nWhen the sealed promotion workflow uses a dedicated GitHub App, user, or team\nalready declared by release governance, repeat `--bypass-app`, `--bypass-user`,\nor `--bypass-team` to project that exact actor into the ruleset. Bypass actors\nare never inferred and broad repository or organization roles are not accepted.\nThis keeps ordinary feature PRs on the predecessor-aligned queue path while the\nsealed publication authority can finish its machine-verified bookkeeping. The\ndry-run receipt exposes the exact actor IDs before `--apply` changes GitHub.\n\nBuildchain provides the reusable\n`.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a\nscheduled or manual \"merge ready dev PRs\" pass. The consumer repository owns\nthe trigger schedule, but the merge decision is declared through workflow\ninputs: target dev branch, required status/check names, ready and block labels,\nallowed work-branch prefixes, review requirements, maximum merges per run,\nmerge method, and dry-run mode.\n\nAgent delivery uses the targeted Buildchain command instead of relying on a\nscheduled scan:\n\n```sh\nbuildchain dev pr-admit \\\n  --repository kungfu-systems/example \\\n  --branch dev/v3/v3.0 \\\n  --pull-request 123 \\\n  --expected-head 0123456789abcdef0123456789abcdef01234567\n```\n\nThe default is a mutation-free plan. After reviewing it, add `--execute` to\nestablish the configured readiness label for only that PR and exact head, read\nthe state back, and attempt native queue admission. Repeating execute is\nidempotent: an exact matching queue entry is adopted, not submitted again. A\nstale head or base, fork, draft, block label, missing approval, failed check,\nactive predecessor, or rejected enqueue exits nonzero. Execute mode also\ncreates or updates an exact-head PR comment and named commit status containing\nthe current state, reason, receipt root, and copyable next action. The JSON\nreceipt remains the complete content-addressed evidence.\n\nGitHub auto-merge is observed but is never readiness or admission authority.\nApproval plus green checks plus auto-merge enabled does not qualify a PR that\nlacks explicit Buildchain delivery intent. The targeted workflow interface\nexposes the same contract through `expected-pr-number` and\n`expected-head-sha`; cadence patrol runs leave those inputs empty.\n\nThe workflow defaults are conservative. A PR is skipped unless it targets the\nconfigured dev line, is not a draft, has the ready label, has no block label,\ncomes from the same repository, uses an allowed work-branch prefix, has a\ncurrent approval, is mergeable, and has the configured required checks passing.\n`landing-mode: auto` reads the target branch's native merge-queue state. When a\nqueue exists, Buildchain never calls the direct merge endpoint: it admits at\nmost one PR against the observed target-branch SHA and immutable PR head, then\ncalls GraphQL `enqueuePullRequest` with `expectedHeadOid`. GitHub's\n`merge_group` checks remain the final authority for the projected merge.\n\nThe admission receipt records the expected and observed base/head SHAs, policy\nchecks, decision, reason, and active predecessor. Buildchain re-reads the base,\nhead, mergeability, and native queue immediately before enqueueing. Base or\nhead drift fails closed, an active queue entry blocks admission, and a rejected\nready predecessor leaves its PR open while later PRs receive\n`blocked-by-predecessor`. Workflow concurrency serializes Buildchain-owned\nadmission runs; GitHub still owns the atomic queue and protected-ref update.\nRepositories may explicitly select `landing-mode: direct` only when the target\nbranch has no native queue. Queue presence always disables the direct path.\n\nFor slow candidates on a frequently advancing dev line, the optional\n[Dev Delivery Warrant Queue](dev-delivery-warrant.md) adds durable FIFO plus\naging scheduling before native queue admission. It separates reusable source\nqualification from exact merge-group integration, uses expected-old Git-ref\nupdates and fenced leases, and keeps the PR head unchanged when only dev moves.\nThe reusable caller supports `off`, read-only `shadow`, and fail-closed\n`required` rollout modes. GitHub Merge Queue remains the final protected-ref\nauthority in every mode.\n\nBounded-concurrency experiments use the separate effect-disabled Warrant\nshadow planner. It may evaluate at most two fully bound lanes from one exact\nobservation, but it cannot mint a second production Warrant or mutate GitHub.\nIts aggregate threshold decision is qualification evidence for a later rollout\nchange, not authority to change the live single-flight policy.\n\nThe canonical consumer required check context is `check / check`, matching the\nreusable workflow call plus its `check` job. Buildchain's own `Verify` workflow\nemits the repository-local context `check`, so Buildchain self-promotion,\nrelease-line bootstrap, and dogfood patrol wrappers pass `check` explicitly.\nRelease governance preserves the exact context emitted by the repository and\nrecords branch-protection policy before/after facts; it does not rewrite one\ncontext shape into the other. Consumer repositories can keep their context\nstable while changing the actual verification command declaratively in\n`buildchain.toml`:\n\nBefore a release caller is merged, consumers should also verify its exact\nreusable-workflow call contract. The checker reads the caller and an already\nchecked-out exact Buildchain commit; it never resolves a floating ref or starts\na release. It rejects unknown or missing inputs and secrets, literal type\ndrift, insufficient permissions, untrusted event classes, and a caller pin that\ndoes not equal the checked callee commit. Defaults, workflow bytes, and the\ncomplete interface are bound into `contractRoot`; the receipt additionally\nbinds the caller commit/tree and both workflow digests.\n\n```sh\nnode .buildchain/workflow-contract-runtime/scripts/workflow-call-contract.mjs check \\\n  --caller-root . \\\n  --caller-workflow .github/workflows/release-new-version.yml \\\n  --caller-repository kungfu-systems/example \\\n  --job promote \\\n  --callee-root .buildchain/workflow-contract-runtime \\\n  --callee-workflow .github/workflows/release-candidate-promote.yml \\\n  --callee-repository kungfu-systems/buildchain \\\n  --trusted-event workflow_dispatch \\\n  --trusted-event pull_request:closed \\\n  --expected-contract-root \"$(cat .buildchain/release-call-contract-root)\" \\\n  --output .buildchain/workflow-call-receipts/release-new-version.json\n```\n\nThe checkout at `.buildchain/workflow-contract-runtime` must use the same\n40-character SHA written in the caller's `uses:` edge. To accept an intentional\ncontract change, first run without `--expected-contract-root`, review the full\ndiagnostic and exact coordinates, then replace only the committed root. The\nordinary PR check runs this command before any candidate or promotion dispatch.\nLocal pre-commit rehearsal may add `--allow-dirty`; that result is marked\n`receiptReusable: false` and cannot replace the clean exact-source receipt.\n\n```toml\n[lifecycle.install]\ncommand = \"cargo fetch --locked\"\n\n[lifecycle.verify]\ncommand = \"cargo test --workspace --locked\"\n```\n\nConsumers that want Buildchain to own the check wrapper can call\n`.github/workflows/check.yml@v3`. The wrapper runs the declared\n`lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when\neither declaration is missing or the command exits non-zero.\n\nDevelopment pull requests that need source acceptance without product build or\nartifact verification can opt into `mode: source`. That mode runs only\n`lifecycle.install` and `lifecycle.check` on GitHub-hosted `ubuntu-24.04` while\npreserving the stable `check / check` required-check context. Existing callers\nremain on `mode: verify` by default, and callers may set\n`upload-artifacts: false` without weakening the job conclusion.\n\nTypical consumer wrapper:\n\n```yaml\nname: Merge Ready Dev PRs\n\non:\n  schedule:\n    - cron: \"17 * * * *\"\n  workflow_dispatch:\n    inputs:\n      dry-run:\n        type: boolean\n        default: true\n\njobs:\n  merge-dev:\n    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3\n    permissions:\n      contents: write\n      pull-requests: write\n      checks: read\n      statuses: write\n    with:\n      target-branch: dev/v3/v3.0\n      required-status-checks: check / check\n      queue-admission-context: Queue admission lease\n      ready-label: ready\n      block-labels: blocked,do-not-merge\n      max-merges: 1\n      landing-mode: auto\n      dry-run: ${{ inputs.dry-run || false }}\n```\n\nWhen the protected branch requires a merge-group-only queue lease, the wrapper\nposts that configured context as a temporary success status on the exact PR\nhead only after the ready, review, and required-check gates pass. It then\nenqueues with `expectedHeadOid`; a rejected enqueue rewrites the temporary\nstatus to failure, while the merge group must still produce its own final check.\n\n## Buildchain Patrol\n\n`dev-pr-auto-merge.yml` remains the focused merge primitive. For repositories\nthat want a stable day-to-day operations contract, Buildchain also exposes a\npatrol workflow family:\n\n| Workflow                                         | Intended cadence                   | Default intent                                                                             |\n| ------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------ |\n| `.github/workflows/patrol-daily.yml`             | daily                              | lightweight inspection plus ready dev PR maintenance                                       |\n| `.github/workflows/patrol-weekly.yml`            | weekly                             | release-state, passport, gate, and stale-state health checks as they are added             |\n| `.github/workflows/patrol-monthly.yml`           | monthly                            | governance, permission, branch-protection, and workflow drift checks as they are added     |\n| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule           | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |\n| `.github/workflows/stable-candidate-patrol.yml`  | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR                |\n\nThe cadence names describe patrol intensity, not release cadence:\n\n- daily patrol can run every day without implying a daily release;\n- weekly patrol is for medium-cost maintenance and audit checks;\n- monthly patrol is for structural drift checks that should not block ordinary\n  development velocity.\n\nEvery cadence result is typed `runKind: cadence-patrol` with\n`qualification: false`. A run with no open candidates reports\n`no-op-no-candidates`; a run where every candidate is skipped reports\n`no-op-all-skipped`. Either no-op can keep maintenance green, but neither is a\ndelivery qualification, a targeted admission receipt, or evidence that an\nexpected PR entered the merge queue.\n\nStable Candidate Patrol is separate from those maintenance cadences because its\ncaller-owned cron is a release-intent window. Its candidate ledger and selection\nremain generic; registry-specific side effects still run through the normal\nrepository `lifecycle.publish` transaction. See\n[`stable-candidate-patrol.md`](stable-candidate-patrol.md).\n\nObserved data that is mechanically regenerated and path-scoped uses the\nseparate [`Observed Evidence Patrol`](observed-evidence-patrol.md) contract.\nIts one-time mechanism changes remain reviewed, while steady-state snapshot\nrefreshes publish directly from trusted default-branch schedule/manual callers.\n\nConsumers should schedule thin callers and keep their YAML declarative. For\nexample:\n\n```yaml\nname: Buildchain Daily Patrol\n\non:\n  schedule:\n    - cron: \"17 2 * * *\"\n  workflow_dispatch:\n\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v3\n    with:\n      dry-run: false\n      max-actions: 1\n```\n\nWeekly and monthly callers use the matching wrapper:\n\n```yaml\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v3\n    with:\n      dry-run: true\n```\n\nAll three wrappers default to the `v3` floating Buildchain runtime. When\n`target-branch` is omitted, the caller's current/default branch selects the\nactive semver dev line, so consumers do not pin patrol to a stale minor branch.\nThe separate workflow names keep consumer schedules readable and stable while\nBuildchain adds new checks behind the cadence wrappers.\n\nBranch and pull-request residue uses the separate\n[`Engineering Housekeeper`](engineering-housekeeper.md) contract. Its reusable\nsurface remains report-first, while Buildchain's committed daily, weekly, and\nmonthly callers run unattended apply across all discovered protected mainlines.\nOnly the positive temporary-development allowlist is mutable; unknown branch\nfamilies remain report-only. Every apply still requires the caller's explicit\ntwo-part policy inputs, exact provider-state revalidation, scoped job\npermissions, and rooted plan/report/receipt evidence.\n\n## Package-Manager Adapters\n\nOld ABV assumed JavaScript repositories with root version state and often\nLerna. Buildchain keeps the version-state contract but does not assume every\nrepository is yarn/Lerna.\n\nThe promotion action discovers and updates:\n\n- root `package.json`;\n- `lerna.json`;\n- package manifests from `package.json` workspaces;\n- package manifests from `lerna.json` packages;\n- package manifests from `pnpm-workspace.yaml`.\n\nIt then runs the repository's detected package manager semantics where needed:\n\n- pnpm repositories use pnpm-oriented workspace discovery;\n- npm repositories use npm/package-lock semantics where present;\n- yarn repositories use yarn-style metadata where present.\n\nFor Buildchain itself, version state is required. For a consumer repository that\nhas no package manifest, the same action can degrade to ref-only behavior only\nwhen that is explicitly allowed by the caller.\n\n## Lifecycle Configuration\n\n`.buildchain/buildchain.toml` is the v3 user configuration format. It lets a repository\ndeclare version-state files and lifecycle commands without pretending every\nproject is a Node workspace. Supported version files include JSON, TOML, and\nregex-based files such as `CMakeLists.txt` or `conanfile.py`.\n\nThe promotion action consumes `version.files`, optional\n`version.derived_files`, and `lifecycle.verify`. Semver and anchored/manual\nrepositories may both declare lifecycle-regenerated tracked outputs as derived\nfiles; anchored/manual repositories additionally bind them into their committed\nversion witnesses.\nThe verify stage runs after generated version-state changes are applied locally\nand before any release refs move. If `verification-command` is passed directly\nto the action, that explicit command overrides `lifecycle.verify`.\n\nAnchored/manual repositories may use `version.derived_files` for committed\nversion witnesses that are regenerated by `lifecycle.version-state`. The\nrelease-candidate build verifies those witnesses before heavy builds and records\ntheir digests with the exact alpha and release tree identities. Promotion then\naccepts only declared version files, the anchor manifest, and those derived\nfiles as differences from the tested alpha tree; release passports preserve the\nsame material binding.\n\nProtected release-line branches keep their normal human review gate. Managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured\nwith one required approving review, required GitHub Actions checks, administrator\nenforcement, conversation resolution, no force pushes, and no deletions. Each\ntarget uses the exact check set, GitHub App identity, and strictness declared by\nthe governance authority descriptor. The\nreusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, which lets the workflow's\nautomation identity apply generated version-state or post-publish channel\nbookkeeping after the reviewed channel PR has merged. Direct\n`promote-buildchain-ref` callers may opt into that one controlled bypass with\n`branch-protection-bypass-apps: github-actions`; every other App slug and all\nuser or team bypass actors are rejected. Before\npatching a protected generated bookkeeping ref, the action creates the\nfull configured required-check set on the exact generated version-state commit, so strict\nstatus checks are satisfied by machine-verifiable Buildchain evidence rather\nthan a human PR. The protected ref PATCH itself uses the generated ref update\ntoken; the reusable wrapper binds it to the run-scoped `github.token`. If direct generated\nrelease finalization bookkeeping is still rejected, Buildchain creates or\nreuses a same-repository `buildchain/version-state/*` PR and records\n`finalization-needed=true` in the durable transaction output. Strict alpha\nfollows the same provider-enforced PR path for its alpha and dev bookkeeping.\nThe PR remains subject to the declared review, required checks, and merge-queue\npolicy; publication resumes idempotently after that protected transaction\nlands.\n\nFor a stable release, the wrapper also checks out the exact current development\nchannel into `.buildchain/reconciliation/dev`. When the prepared next-alpha\ncommit cannot fast-forward dev because reviewed work landed concurrently, the\npromotion action applies the next version to that checkout, regenerates every\ndeclared derived version-state file, reruns the verification lifecycle, and\nonly then creates the two-parent reconciliation commit. A checkout/current-ref\nSHA mismatch blocks reconciliation instead of committing stale projections.\nBuildchain's own promotion workflow accepts only\n`BUILDCHAIN_PROMOTION_BYPASS_APPS=github-actions`, defaulting to that exact App\nwhen the variable is absent. Buildchain's release-line bootstrap uses the\nadministrator-scoped promotion token only to configure protection; branch\ncreation and generated ref updates use the run-scoped token. New channel\nprotection binds required checks to GitHub Actions App id `15368`, enables Code\nOwner, stale-review, and latest-push review gates, and admits no user or team\nbypass actor.\n\n## What This Guarantees\n\nWhen the loop succeeds, maintainers and consumers can rely on these facts:\n\n- every production release has an exact tag such as `v3.0.2`;\n- every production minor line has a floating tag such as `v3.0`;\n- every selected stable major has a floating tag such as `v3`;\n- every next-major release is driven by a reviewed `release -> publish-gate/major` PR,\n  not a hidden manual button;\n- every test channel has an exact alpha tag such as `v3.0.3-alpha.0`;\n- every alpha minor line has a floating tag such as `v3.0-alpha`;\n- every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;\n- version manifests match the tag visible from the same commit;\n- production releases are derived from the alpha tree that was tested;\n- manual non-dry-run promotion cannot bypass PR review and verification;\n- flow-internal automation bypasses apply only to declared GitHub Apps, users,\n  or teams on Buildchain-managed channel branch protection, while one-review\n  protection remains enforced for humans;\n- admin users cannot make a channel promotion valid by temporarily bypassing\n  branch protection.\n\nThis is the practical meaning of \"governance closed loop\" in Buildchain: the\ndecision, code, version state, and Git refs close over the same evidence chain.\n\n## What This Does Not Do\n\nBuildchain release promotion does not embed registry clients or product-specific\npublish logic. When publish transactions are enabled, `promote-buildchain-ref`\ncan run the consumer's `lifecycle.publish` command and own the transaction,\nevidence validation, durable recovery state, and ref finalization order. The\nconsumer repository still owns registry truth: npm, PyPI, OCI, S3, Conan, CMake\npackaging, download pages, dist-tags, and similar side effects must be\nimplemented by project lifecycle commands that emit Buildchain publish evidence.\n\nDurable transaction recovery is also bound to the exact publication version\nplanned for the current run. An unfinished transaction may be resumed from the\ncurrent source or its history only when its recorded version matches that plan;\nan older failed transaction that happens to be an ancestor cannot reserve its\nold exact tag for a newer package publication.\n\nThe exact tag is also part of the durable transaction identity. If an anchored\npackage publication completed registry side effects under a stale internal tag\nselection, a retry may rebind the unfinished `published` or `finalizing`\ntransaction to the newly planned internal tag only when the package version,\nsource, release material, target, complete artifact set, and evidence all still\nmatch; the stale tag must not point at the transaction, and the requested tag\nmust be absent or already point at accepted release material. This preserves an\nimmutable tag that represents a completed transaction while allowing a tag\ncollision discovered after registry publication to recover without republishing.\n\nFor package publish transactions, the immutable public version tag points to\nthe transaction `source_sha`, so registry source metadata such as npm `gitHead`\nand the Git tag identify the same source commit. Protected branches and mutable\nchannel tags continue to point to the generated `release_sha`. Recovery accepts\nolder completed transactions whose exact tags already point to recorded release\nor release-material SHAs, but new tags are source-bound.\n\nEvery Buildchain publish model that can run registry side effects must bind the\npublish entrypoint to an immutable `publish-gate/*` source lock. The reusable\n`release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and\npasses `require-publish-source-lock`, `publish-source-ref`,\n`publish-source-sha`, and `publish-source-locked` to\n`promote-buildchain-ref`. Direct action callers must pass the same four inputs\nfrom the reusable build outputs. Workflows that only collect passports or run\ndry-run package checks do not move publish refs and are not publish-gate\npublication models. A dry-run of `release-candidate-promote.yml` computes and\nreports the exact `publish-gate/*` source lock that a real promotion would use,\nbut does not read, create, or move that ref.\n\nSemver GitHub Release publication is owned by `promote-buildchain-ref`, not by\nconsumer shell glue. Consumers normally use the `release-candidate-promote.yml`\ngenerated channel router, where GitHub Release publication is enabled by default and can be\ndisabled with `github-release: false`; the wrapper passes that declaration to\nthe action. After the publish transaction reaches `complete`, Buildchain creates\nor updates the public GitHub Release and uploads the generated\n`buildchain.release.json`, release-passport assets, and publish evidence. The\nauthoritative publication channel controls GitHub metadata: alpha is marked\n`prerelease=true` and `make_latest=false`; release/stable/major is marked latest.\nSemver tag syntax remains the fallback for ordinary callers without explicit\npublication intent. For anchored/manual package releases, the public\nrelease tag defaults to `v<publishedVersion>` while the internal exact\ntransaction tag remains in the release passport and release-state ref. This is\nthe supported path for downstream\n`release.published` propagation across semver, major, and promote-only release\ncandidate publication models.\n\nPublished GitHub Release assets are immutable evidence. A repeated promotion\npreserves an existing asset when its SHA-256 digest matches the regenerated\nbytes, uploads only missing assets, and fails with an immutable-release\ncollision when a same-name asset has different bytes. It never deletes and\nreplaces an existing asset during retry or duplicate workflow delivery.\nAn explicit candidate recovery whose validated receipt records an already\ncomplete transaction instead verifies the existing public Release Passport\nbundle and preserves its Buildchain-owned evidence generation. Product payload\nbytes remain digest-bound to the restored candidate, and missing product assets\nalone may be filled from that sealed bundle. This exception is unavailable to\nordinary reruns or receipts from earlier transaction states.\n\nProduct payloads are included only through the explicit\n`github-release-payload-patterns` input. Patterns match basenames inside the\ndownloaded PR-stage RC payload bundle; zero matches or duplicate public\nbasenames fail closed. This preserves the exact PR-built bytes instead of\nrebuilding archives during promotion.\n\nConsumers with a signed well-known discovery document can additionally provide\n`publication-commit-command`. The advanced promotion workflow validates its\ntopology before any publish-gate or release mutation, then runs it only after\nthe GitHub Release and its immutable payload/passport assets exist. The command\nmust publicly read back the exact new payload root and emit\n`kungfu-buildchain-publication-commit-evidence/v1`; that evidence is copied\ninto the controller artifact and exposed as workflow outputs. The previous\nauthority must remain valid on every failure. Deferred standalone binary\ndistribution is incompatible with this mode because the discovery authority\nmust be the final product mutation.\n\nBuildchain also does not maintain bare exact tags such as `1.0.0`. The supported\nexact release and alpha refs are v-prefixed:\n\n```text\nv3.0.0\nv3.0.1-alpha.0\n```\n\n## Operational Reading Order\n\nWhen debugging or extending release behavior, read in this order:\n\n1. `docs/release-flow.md`\n2. `.github/workflows/release-verify.yml`\n3. `.github/workflows/buildchain-ref-promotion.yml`\n4. `.github/workflows/release-candidate-promote.yml`\n5. `.github/workflows/.release-candidate-promote.yml`\n6. `actions/promote-buildchain-ref/README.md`\n7. `actions/promote-buildchain-ref/src/`\n8. `docs/migration-inventory.md`\n\nThat path gives the policy first, the workflow trigger second, and the action\nimplementation last."
     },
     {
       "id": "manual:release-passport",

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

@@ -8351,8 +8351,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "613ca42d3fe36e953603221d1cf16478ba84e6cf27dd6d11ddb2c1caea42ec3b",
-    "workflowRegistryDigest": "b2ade24ee445b041ad32e95415b574a29ef8f6ece55fc1b07e09e5c9bcdc5859",
-    "pageRegistryDigest": "278318ddd3f832a3681ff805eff19f9a1e3d7da382c62db10a8be663cdc99139"
+    "workflowRegistryDigest": "46236ec7a619e04a03132940e57ac0397873eebb16f8dad0ec85a68fc27614c7",
+    "pageRegistryDigest": "f0b17d9ba03d8f5387051c1fc17824adbaf0a98becbc55f5b074802d9fe00d6f"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-13T19:32:43.000Z",
-  "publishedAt": "2026-08-13T19:32:43.000Z",
+  "generatedAt": "2026-08-14T01:22:22.000Z",
+  "publishedAt": "2026-08-14T01:22:22.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "45d01565d7039cb8c7bb71ddd4e9f8f43085aea3",
+  "sourceRevision": "17cb4259831b34ba382b0211500cbb1ef26efd11",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.9-alpha.16",
+    "version": "3.0.9-alpha.17",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",