@kungfu-tech/buildchain 3.0.1-alpha.2 → 3.0.1-alpha.4

package/docs/release-candidate.md

@@ -14,7 +14,7 @@ Enable it on the reusable build workflow:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       artifact-name: libnode
       release-candidate: true
@@ -44,7 +44,7 @@ contains:
 Promotion workflows that should not rebuild artifacts can enable:
 
 ```yaml
-- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3
   with:
     token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
     sha: ${{ needs.build.outputs.publish-source-sha }}
@@ -72,7 +72,7 @@ generates one before calling `promote-buildchain-ref`. Before that call, the
 wrapper creates or updates `publish-gate/{alpha,release,major}` to the
 promotion channel commit and passes that ref, target SHA, and `locked=true` to
 the promote action with `require-publish-source-lock: "true"`. Consumers using
-floating `@v2` therefore get publish-side source-lock drift protection without
+floating `@v3` therefore get publish-side source-lock drift protection without
 copying resolver or promote YAML. The default npm path
 generates that requirement list from the downloaded `.tgz` payloads themselves:
 Buildchain reads `package/package.json` inside each tarball for the real scoped
@@ -135,7 +135,7 @@ pre-build/artifact evidence into the wrapper:
 ```yaml
 jobs:
   promote:
-    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3
     with:
       buildchain-channel: auto
       buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json

package/docs/release-governance.md

@@ -136,7 +136,7 @@ continue from the same SHA without another native build or an administrator
 merge bypass.
 
 Repositories may also expose a small caller workflow around
-`.github/workflows/release-governance-reconcile.yml@v2`. Pass `branch`,
+`.github/workflows/release-governance-reconcile.yml@v3`. Pass `branch`,
 `candidate-sha`, and `apply`, and provide `governance-token` through the caller's
 secrets. The reusable workflow uploads the JSON reconciliation receipt.
 
@@ -181,14 +181,14 @@ This is why Buildchain maintains both exact and floating refs:
 - `v2` is the selected stable major-line entrypoint;
 - `v2.0.3-alpha.0` is immutable alpha evidence;
 - `v2.0-alpha` is the latest test channel for the `2.0` line.
-- `v2-alpha` is the latest test channel on the highest published alpha minor in major `2`.
+- `v3-alpha` is the latest test channel on the highest published alpha minor in major `2`.
 
 A release does not mean "minor is complete." It means "this patch on this minor
 line is now production."
 
 GitHub repository rules must preserve that distinction. Exact tags such as
 `v2.0.2` and `v2.0.3-alpha.0` should be immutable. Floating channel tags such as
-`v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` must remain movable by the Buildchain promotion
+`v2`, `v2.0`, `v2.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion
 token after governance checks and publish evidence pass. A tag ruleset that
 protects every `refs/tags/v*` ref is too broad because it also locks the
 floating channel tags that Buildchain is required to update. Prefer exact-tag
@@ -221,7 +221,7 @@ line-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`
 channel backward. Exact prerelease versions remain installable directly.
 
 This keeps the test channel self-describing. If a consumer checks out
-`v2.0-alpha` or `v2-alpha`, the manifests and exact alpha tag agree. The major
+`v2.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major
 alpha ref removes routine consumer edits when Buildchain opens a newer minor,
 while exact tags and SHAs remain the reproducible audit choice.
 
@@ -229,8 +229,8 @@ while exact tags and SHAs remain the reproducible audit choice.
 
 Buildchain continuously consumes its own current major alpha through
 `.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
-released channel router at `build.yml@v2-alpha`. The auto lane must resolve
-`v2-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
+released channel router at `build.yml@v3-alpha`. The auto lane must resolve
+`v3-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
 declared install, build, and verify fixture, proving that a single consumer
 surface routes to distinct released runtimes without duplicating lifecycle
 configuration in the consumer.
@@ -246,7 +246,7 @@ reviewed alpha SHA and compatibility digest; it does not replace the stable
 consumer lock. A later alpha with only compatible additive drift continues,
 while a changed breaking digest fails until the new alpha contract is reviewed.
 
-The evidence job resolves `v2-alpha` and `v2` through the GitHub refs API,
+The evidence job resolves `v3-alpha` and `v2` through the GitHub refs API,
 compares those immutable SHAs with the reusable workflow outputs, verifies the
 `alpha` and `stable` classifications, and uploads a JSON evidence artifact.
 The canary runs after successful Buildchain ref promotion, on a daily fallback
@@ -545,7 +545,7 @@ command = "cargo test --workspace --locked"
 ```
 
 Consumers that want Buildchain to own the check wrapper can call
-`.github/workflows/check.yml@v2`. The wrapper runs the declared
+`.github/workflows/check.yml@v3`. The wrapper runs the declared
 `lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when
 either declaration is missing or the command exits non-zero.
 
@@ -572,7 +572,7 @@ on:
 
 jobs:
   merge-dev:
-    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3
     permissions:
       contents: write
       pull-requests: write
@@ -633,7 +633,7 @@ on:
 
 jobs:
   patrol:
-    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v3
     with:
       dry-run: false
       max-actions: 1
@@ -644,7 +644,7 @@ Weekly and monthly callers use the matching wrapper:
 ```yaml
 jobs:
   patrol:
-    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v3
     with:
       dry-run: true
 ```
@@ -753,7 +753,7 @@ When the loop succeeds, maintainers and consumers can rely on these facts:
   not a hidden manual button;
 - every test channel has an exact alpha tag such as `v2.0.3-alpha.0`;
 - every alpha minor line has a floating tag such as `v2.0-alpha`;
-- every major with a published alpha has a cross-minor floating tag such as `v2-alpha`, owned by its highest published alpha minor;
+- every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;
 - version manifests match the tag visible from the same commit;
 - production releases are derived from the alpha tree that was tested;
 - manual non-dry-run promotion cannot bypass PR review and verification;
@@ -794,7 +794,7 @@ collision discovered after registry publication to recover without republishing.
 
 Every Buildchain publish model that can run registry side effects must bind the
 publish entrypoint to an immutable `publish-gate/*` source lock. The reusable
-`release-candidate-promote.yml@v2` wrapper creates or updates that gate ref and
+`release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and
 passes `require-publish-source-lock`, `publish-source-ref`,
 `publish-source-sha`, and `publish-source-locked` to
 `promote-buildchain-ref`. Direct action callers must pass the same four inputs

package/docs/release-passport.md

@@ -127,11 +127,11 @@ Generate a local release passport bundle from release assets:
 
 ```bash
 buildchain collect github-release \
-  --tag v2.2.0 \
+  --tag v3.0.0 \
   --repository kungfu-systems/buildchain \
   --assets-dir dist \
-  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \
-  --transaction-json .buildchain/release-state/v2.2.0/state.json \
+  --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \
+  --transaction-json .buildchain/release-state/v3.0.0/state.json \
   --package-set-json package-set.json \
   --anchor-manifest-json libnode.release.json \
   --build-summary-json .buildchain/artifacts/build-summary.json \
@@ -140,7 +140,7 @@ buildchain collect github-release \
   --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
-  --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \
+  --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \
   --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
   --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
   --invariant-passport-json product/release/qualification/invariant-passport.json \
@@ -288,7 +288,7 @@ current source/artifact hashes and generates:
   surfaces.
 
 The generated claim set covers Buildchain's KFD release passport support,
-agent-first single source of truth, floating `@v2` contract drift protection,
+agent-first single source of truth, floating `@v3` contract drift protection,
 semver GitHub Release evidence publication, channel-preserving release
 propagation, and npm publish evidence/finalization. Buildchain self promotion
 passes those files into `promote-buildchain-ref`; `verifyReleasePassport()` then
@@ -391,7 +391,7 @@ and compares it before heavy build or publish work begins.
 
 Compatible drift, such as optional inputs or extra diagnostics, continues and
 creates a consumer-local issue for review. Breaking drift fails fast. This means
-consumers can use `@v2` without silently accepting incompatible changes, while
+consumers can use `@v3` without silently accepting incompatible changes, while
 Buildchain maintainers can still ship compatible improvements under the same
 major floating tag.
 

package/docs/release-propagation.md

@@ -169,19 +169,19 @@ The written lock has contract
 ## Reusable Workflow
 
 Upstream repositories can call
-`.github/workflows/release-propagation.yml@v2` after release finalization:
+`.github/workflows/release-propagation.yml@v3` after release finalization:
 
 ```yaml
 jobs:
   propagate-site:
-    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v3
     with:
-      buildchain-ref: v2
+      buildchain-ref: v3
       graph-json: ${{ needs.release.outputs.propagation-graph-json }}
       upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}
       downstream-target: site-libkungfu-dev
       downstream-repository: kungfu-systems/site-libkungfu-dev
-      downstream-base-ref: dev/v2/v2.7
+      downstream-base-ref: main
       downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts
       downstream-verify-command: pnpm run check
       dry-run: false
@@ -219,7 +219,7 @@ PR updates source-of-truth facts, then downstream alpha or release publication
 runs through its own protected channel. A byte-identical rerun is an explicit
 successful no-op.
 For unreleased runtime validation, keep the caller's reusable workflow reference
-on `@v2` and pass a temporary train ref through `buildchain-ref`.
+on `@v3` and pass a temporary train ref through `buildchain-ref`.
 
 ## kfd to site-libkungfu-dev
 

package/docs/reusable-build-surface.md

@@ -14,7 +14,7 @@ development and stable release work:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3
     permissions:
       contents: read
       issues: write
@@ -56,8 +56,8 @@ with:
 ```
 
 During the v2.12 prerelease evaluation window, canaries use
-`build.yml@v2-alpha`. The same router then selects `v2-alpha` or stable `v2` as
-the runtime. Production consumers should adopt `build.yml@v2` after the router
+`build.yml@v3-alpha`. The same router then selects `v3-alpha` or stable `v2` as
+the runtime. Production consumers should adopt `build.yml@v3` after the router
 has reached stable; this keeps the routing shell itself on a stable ref.
 
 The router is generated from `.build.yml`'s input/output surface. Run
@@ -72,7 +72,7 @@ surface:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       working-directory: .
       artifact-name: libnode
@@ -136,7 +136,7 @@ Python, uv, and fnm, but do not need native compilation:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       runner-preset: kungfu-v4-self-hosted
       linux-container-preset: kungfu-verify
@@ -217,7 +217,7 @@ on a host runner until their image contract is explicit.
 ## Buildchain Runtime Override
 
 Stable consumers should keep the reusable workflow pinned to stable refs such as
-`@v2`. The optional `buildchain-ref` input is empty by default; empty means
+`@v3`. The optional `buildchain-ref` input is empty by default; empty means
 Buildchain resolves and executes the stable runtime selected by the workflow
 shell. The full train validation protocol is documented in
 [`runtime-train-validation.md`](runtime-train-validation.md).
@@ -236,7 +236,7 @@ on:
 
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       buildchain-ref: ${{ inputs.buildchain-ref || '' }}
 ```
@@ -245,8 +245,8 @@ Allowed override refs are deliberately narrow:
 
 | Ref form | Meaning |
 | --- | --- |
-| `train/v2/v2.3/<capability>` | Temporary capability train under the active minor line |
-| `refs/heads/train/v2/v2.3/<capability>` | Explicit branch ref for the same train |
+| `train/v3/v3.0/<capability>` | Temporary capability train under the active minor line |
+| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train |
 | `<40-character SHA>` | Exact immutable Buildchain runtime commit |
 
 Override requests fail closed unless the event is `workflow_dispatch` and the
@@ -270,7 +270,7 @@ workflow path or a temporary explicit workflow ref.
 
 ## Floating Ref Contract Lock
 
-Stable consumers should use floating major refs such as `@v2`, but a floating
+Stable consumers should use floating major refs such as `@v3`, but a floating
 ref is not blind trust. Each released Buildchain ref carries a package-owned
 runtime contract world in `dist/site/buildchain-contract.json`. Consumers may
 keep a small lock file, `.buildchain/contract-lock.json`, recording the
@@ -295,7 +295,7 @@ the default `major-compatible` policy.
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     permissions:
       contents: read
       issues: write
@@ -323,13 +323,13 @@ Advanced alpha-channel consumers select the matching workflow shell:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2-alpha
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3-alpha
     with:
       buildchain-contract-lock-path: .buildchain/contract-lock.json
 ```
 
 The runtime follows the called workflow through `job.workflow_ref`. Callers may
-also pass `buildchain-ref: v2-alpha` explicitly; official floating refs are
+also pass `buildchain-ref: v3-alpha` explicitly; official floating refs are
 ordinary channel selections and are allowed on pull requests and pushes. Train
 refs and exact SHAs remain trusted manual overrides.
 
@@ -345,7 +345,7 @@ semantics remain owned by the consumer's pinned Shifu implementation.
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3
     with:
       shifu-cache-profile-ref: ${{ vars.SHIFU_CACHE_PROFILE_REF }}
       shifu-cache-profile-digest: ${{ vars.SHIFU_CACHE_PROFILE_DIGEST }}
@@ -377,7 +377,7 @@ lifecycle commands run.
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       runner-preset: kungfu-v4-self-hosted
       checkout-cache-mode: auto
@@ -445,8 +445,8 @@ When a Buildchain maintainer asks for downstream validation, the expected
 request is:
 
 ```text
-Buildchain train ready: buildchain-ref=train/v2/v2.3/<capability>.
-Keep uses: ...@v2; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
+Buildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.
+Keep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
 ```
 
 After validation succeeds, the Buildchain change should continue through the
@@ -591,7 +591,7 @@ Large self-hosted native builds can opt into the first-class S3 relay path:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       runner-preset: kungfu-v4-self-hosted
       artifact-transfer-mode: s3-to-github-artifacts
@@ -670,7 +670,7 @@ Use `publish-channel` to request a channel:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       publish-channel: release
 
@@ -796,7 +796,7 @@ calls `actions/promote-buildchain-ref` with
 `promote-only-release-candidate: "true"` and
 `require-publish-source-lock: "true"`. The wrapper passes the created
 `publish-gate/*` ref, target SHA, and `locked=true` into the promote action, so
-floating `@v2` consumers receive publish-side source-lock drift protection by
+floating `@v3` consumers receive publish-side source-lock drift protection by
 default. It also defaults `branch-protection-bypass-apps` to `github-actions`
 so the workflow automation can apply generated version-state and channel
 bookkeeping on protected `dev`/`alpha`/`release` branches after the reviewed
@@ -840,7 +840,7 @@ candidate passport, and the final release passport record these identities.
 ```yaml
 jobs:
   promote:
-    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3
     secrets:
       buildchain-issue-app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}
       buildchain-issue-app-private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}
@@ -939,7 +939,7 @@ publish side effect:
 
 ```yaml
 - name: Promote release ref and publish npm package set
-  uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+  uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3
   with:
     sha: ${{ needs.build.outputs.publish-source-sha }}
     target-ref: release/v22/v22.22
@@ -1042,7 +1042,7 @@ sampler path as optional during verify; an explicitly supplied
 For custom workflows, use the action directly:
 
 ```yaml
-- uses: kungfu-systems/buildchain/actions/run-lifecycle@v2
+- uses: kungfu-systems/buildchain/actions/run-lifecycle@v3
   with:
     stage: build
     required: "true"

package/docs/runtime-train-validation.md

@@ -1,14 +1,14 @@
 # Runtime Train Validation
 
-Buildchain consumers should keep stable workflow refs such as `@v2` in
+Buildchain consumers should keep stable workflow refs such as `@v3` in
 committed workflow YAML. Runtime trains provide a temporary validation pointer
 for Buildchain changes that are ready for downstream testing but not yet
 promoted through the normal `dev -> alpha -> release` chain.
 
 Official floating channels are not runtime overrides. A consumer that
-deliberately follows `@v2-alpha` gets the matching runtime on pull requests and
+deliberately follows `@v3-alpha` gets the matching runtime on pull requests and
 pushes because the reusable workflow reads the called workflow identity from
-`job.workflow_ref`. Passing `buildchain-ref: v2-alpha` explicitly is also
+`job.workflow_ref`. Passing `buildchain-ref: v3-alpha` explicitly is also
 accepted when the caller wants the channel binding visible in its input set.
 The caller's `github.workflow_ref` is not used for this inference because it
 identifies the caller workflow during reusable calls.
@@ -18,7 +18,7 @@ identifies the caller workflow during reusable calls.
 A train ref is a branch in the Buildchain repository:
 
 ```text
-train/v2/v2.3/<capability>
+train/v3/v3.0/<capability>
 ```
 
 It is a validation pointer, not a release channel:
@@ -41,15 +41,15 @@ When a Buildchain change needs downstream validation before stable refs move,
 publish a train ref before asking consumers to test it:
 
 ```sh
-git push origin HEAD:refs/heads/train/v2/v2.3/<capability>
+git push origin HEAD:refs/heads/train/v3/v3.0/<capability>
 ```
 
 Use a capability slug that names the behavior being validated, for example:
 
 ```text
-train/v2/v2.3/runtime-loader
-train/v2/v2.3/toolkit-diagnostics
-train/v2/v2.3/site-source-of-truth
+train/v3/v3.0/runtime-loader
+train/v3/v3.0/toolkit-diagnostics
+train/v3/v3.0/site-source-of-truth
 ```
 
 The pull request or validation request should include the train ref, the exact
@@ -71,7 +71,7 @@ Consumers keep their reusable workflow pinned to the stable shell:
 ```yaml
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
 ```
 
 To validate a train without committing temporary workflow refs, expose a
@@ -88,7 +88,7 @@ on:
 
 jobs:
   build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
     with:
       buildchain-ref: ${{ inputs.buildchain-ref || '' }}
 ```
@@ -101,8 +101,8 @@ consumers that do not have it should add it once before validating a train.
 Use this short request when a train is ready:
 
 ```text
-Buildchain train ready: buildchain-ref=train/v2/v2.3/<capability>.
-Keep uses: ...@v2; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
+Buildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.
+Keep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
 ```
 
 The consumer should run a trusted `workflow_dispatch`, paste the train ref into
@@ -119,7 +119,7 @@ summary. The evidence should include:
 
 ## Trust and limitation
 
-Official floating channel refs such as `v2` and `v2-alpha` may be selected on
+Official floating channel refs such as `v2` and `v3-alpha` may be selected on
 pull requests and pushes. Train refs and arbitrary exact-SHA overrides still
 fail closed unless the event is `workflow_dispatch` and the actor has write,
 maintain, or admin permission on the caller repository. Pull requests,

package/docs/shifu-gate-profiles.md

@@ -97,7 +97,7 @@ per-gate evidence pointers, omissions, and issues.
 ```yaml
 jobs:
   gates:
-    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v3
     with:
       gate-profile: alpha-pr
       runner-preset: kungfu-v4-self-hosted
@@ -105,7 +105,7 @@ jobs:
 
   build:
     needs: gates
-    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3
     with:
       release-candidate: true
       gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}

package/docs/site-bundle-contract.md

@@ -154,7 +154,7 @@ The P0 bundle includes:
 - workflow/action registry;
 - release model facts;
 - artifact and evidence schema index;
-- Buildchain runtime contract world for `@v2` floating-ref compatibility checks,
+- Buildchain runtime contract world for `@v3` floating-ref compatibility checks,
   KFD-1/KFD-2/KFD-3 release gates, GitHub Release evidence publication, and
   site-consumption contracts;
 - Buildchain KFD claim registry for release-passport self verification and

package/docs/stable-candidate-patrol.md

@@ -125,7 +125,7 @@ permissions:
 
 jobs:
   stable:
-    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v3
     with:
       release-now: ${{ inputs.release-now }}
       dry-run: false
@@ -203,7 +203,7 @@ step; the durable authority record remains the candidate ledger entry and PR.
 The default ledger ref is derived from the release line, for example:
 
 ```text
-buildchain/candidate-ledger/v2/v2.12
+buildchain/candidate-ledger/v3/v3.0
 ```
 
 It stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized

package/docs/toolkit-observability.md

@@ -413,6 +413,20 @@ buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4
 Every event records a timestamp. `span` records duration and preserves the
 wrapped command's exit code.
 
+Buildchain also records local control-plane outcome events for workflow-friction
+incident handling and production release-intent PR handling. `log summary`
+reports the observed incident reuse rate, release-intent suppression rate, and
+suppression reasons. A reused incident means an equivalent occurrence found the
+same fingerprint and was commented, cooled down, or otherwise reused; a
+suppressed release intent means Buildchain proved that the source commit already
+had a qualifying merged release PR. These are operational facts, not release
+policy inputs, and logging failure remains non-fatal by default.
+
+The reusable promotion workflow uploads `.buildchain/logs/events.jsonl` when a
+friction report is produced. The web-surface production release PR handoff
+artifact includes the same path, so a real run can falsify the P0 claim instead
+of relying only on unit tests.
+
 ## Release Gate
 
 Buildchain's own binary distribution lane verifies required log events before

package/docs/web-surface-deployments.md

@@ -167,7 +167,7 @@ floating ref, such as:
 ```yaml
 jobs:
   web:
-    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3
     with:
       buildchain-contract-lock-path: .buildchain/contract-lock.json
       buildchain-contract-compatibility-policy: major-compatible
@@ -667,7 +667,7 @@ the standard PR review and promotion flow without copying bespoke glue:
 ```yaml
 jobs:
   web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3
     with:
       build-command: npm run build
       verify-command: npm run check
@@ -686,7 +686,7 @@ The reusable workflow maps GitHub events to Buildchain web-surface semantics:
 
 The optional `buildchain-ref` input is empty by default. Empty keeps the
 web-surface run on the stable Buildchain runtime selected by the reusable
-workflow ref, normally `@v2`. A trusted maintainer can expose a
+workflow ref, normally `@v3`. A trusted maintainer can expose a
 `workflow_dispatch` input and pass it through for one-off train validation.
 See [`runtime-train-validation.md`](runtime-train-validation.md) for the shared
 train protocol and notification template:
@@ -702,7 +702,7 @@ on:
 
 jobs:
   web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3
     with:
       buildchain-ref: ${{ inputs.buildchain-ref || '' }}
       build-command: pnpm run build
@@ -712,7 +712,7 @@ jobs:
 
 Only trusted `workflow_dispatch` runs by repository actors with write,
 maintain, or admin permission may use a non-empty runtime override. Train refs
-such as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not
+such as `train/v3/v3.0/site-source-of-truth` are temporary validation refs, not
 stable production dependencies or pending merge targets. They may remain for a
 retention window after release as a fast-use and rollback channel, with old
 trains handled by periodic Buildchain cleanup. The web-surface deployment
@@ -730,7 +730,7 @@ permissions:
 
 jobs:
   web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3
     with:
       build-command: pnpm run build
       verify-command: pnpm run check
@@ -824,7 +824,7 @@ For release-PR publishing, callers opt in explicitly:
 ```yaml
 jobs:
   web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3
     with:
       build-command: npm run build
       verify-command: npm run check

package/fixtures/libnode-shaped/README.md

@@ -15,7 +15,7 @@ It is intentionally small, but it keeps the important shape:
 - lifecycle commands are Node-based and cross-platform;
 - build output lands under `dist/`, which the reusable build workflow uploads
   with a deterministic artifact name and manifest;
-- `.github/workflows/build.yml` exercises the public `build.yml@v2` channel
+- `.github/workflows/build.yml` exercises the public `build.yml@v3` channel
   router with a caller job named `build`, including its stable top-level
   `build / Summarize build contract` aggregate;
 - the fixture can be resolved through a publish-gate source lock, which binds

package/package.json

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