@kungfu-tech/buildchain 2.12.1 → 2.12.2

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

@@ -4,9 +4,9 @@
   "status": "passed",
   "summary": {
     "cliCommandCount": 76,
-    "workflowCount": 42,
+    "workflowCount": 43,
     "actionCount": 4,
-    "sitePageCount": 46,
+    "sitePageCount": 47,
     "docCommandRefCount": 241,
     "failureCount": 0
   },
@@ -425,6 +425,7 @@
           "checkout-cache-reference-repository-template",
           "checkout-cache-timeout-seconds",
           "expected-artifacts-json",
+          "gate-profile-aggregate-json",
           "install-command",
           "linux-container-image",
           "linux-container-preset",
@@ -456,7 +457,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 57
+        "inputCount": 58
       },
       {
         "id": ".bump-minor-version",
@@ -464,6 +465,32 @@
         "inputs": [],
         "inputCount": 0
       },
+      {
+        "id": ".gate-profile",
+        "path": ".github/workflows/.gate-profile.yml",
+        "inputs": [
+          "artifact-name",
+          "artifact-retention-days",
+          "buildchain-ref",
+          "buildchain-repository",
+          "gate-command-json",
+          "gate-environment-json",
+          "gate-plan-command-json",
+          "gate-profile",
+          "gate-registry",
+          "include-advisory",
+          "node-version",
+          "platforms-json",
+          "require-trusted-event",
+          "runner-preset",
+          "shifu-cache-profile-digest",
+          "shifu-cache-profile-ref",
+          "source-ref",
+          "untrusted-policy",
+          "working-directory"
+        ],
+        "inputCount": 19
+      },
       {
         "id": ".release-docker",
         "path": ".github/workflows/.release-docker.yml",
@@ -730,6 +757,7 @@
           "checkout-cache-reference-repository-template",
           "checkout-cache-timeout-seconds",
           "expected-artifacts-json",
+          "gate-profile-aggregate-json",
           "install-command",
           "linux-container-image",
           "linux-container-preset",
@@ -761,7 +789,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 60
+        "inputCount": 61
       },
       {
         "id": "buildchain-alpha-self-dogfood",
@@ -864,12 +892,13 @@
         "inputs": [
           "buildchain-ref",
           "buildchain-repository",
+          "mode",
           "node-version",
           "require-version-state",
           "upload-artifacts",
           "working-directory"
         ],
-        "inputCount": 6
+        "inputCount": 7
       },
       {
         "id": "dev-pr-auto-merge",
@@ -1452,6 +1481,10 @@
         "id": "manual:runtime-train-validation",
         "category": "manual"
       },
+      {
+        "id": "manual:shifu-gate-profiles",
+        "category": "manual"
+      },
       {
         "id": "manual:site-bundle-contract",
         "category": "manual"
@@ -2690,8 +2723,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "ab57fec294efb9dde1612787bfd0d532b5bb95298b5da14a2b51a5e71b9c7dcc",
-    "workflowRegistryDigest": "c821196e68a63cefb5686b9005a01aeb7d6cf5248a6146d1e276b87ee765e9f6",
-    "pageRegistryDigest": "c4c73230264352bc86f2f4170335ff0c1bb399b4040323627b6f9e10a32d9ea0"
+    "workflowRegistryDigest": "ccc8ab882a30d8c180c109aa484c619d34a5e889c571757f11e555f113c4d338",
+    "pageRegistryDigest": "394ef34331be95e72b6c2c875ce138ea0b3344e539793291dc8126d168a2c1f9"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-13T07:22:41.239Z",
-  "publishedAt": "2026-07-13T07:22:41.239Z",
+  "generatedAt": "2026-07-13T12:43:26.201Z",
+  "publishedAt": "2026-07-13T12:43:26.201Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "699b971025689b6906d085ca456ee81ca6df30e1",
+  "sourceRevision": "d61a8cfd6d147aadc73306dbc97bf2ce6b825895",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.1",
+    "version": "2.12.2",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-13T07:22:41.239Z",
-  "publishedAt": "2026-07-13T07:22:41.239Z",
+  "generatedAt": "2026-07-13T12:43:26.201Z",
+  "publishedAt": "2026-07-13T12:43:26.201Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "699b971025689b6906d085ca456ee81ca6df30e1",
+  "sourceRevision": "d61a8cfd6d147aadc73306dbc97bf2ce6b825895",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.1",
+    "version": "2.12.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:0735009b21cea9227f2c9b9bcbec1219898f4d211776b60aa030ace65821ec80"
+      "digest": "sha256:5df6d6110d7c33da4625a2e1ebb6b778eef9c4420379cff342229bc0b02962e1"
     },
     {
       "id": "install",
@@ -197,7 +197,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:60c39693878258d275e9d47983b306faed35d6416297c14570429de73284604c"
+      "digest": "sha256:3a03359ec58db04f334303256b02020f6039616e8802c19dfc00e76bbb05bf18"
     },
     {
       "id": "reusable-build-surface",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:a868fd50875aa64ae26d8e37a5bfbc4be137ce89be3b0726e97a7a8028a667f4"
+      "digest": "sha256:3ae2bbc2df394726f350e58be1a71dd0379b99b19cd6ccf15fbe3b843f3890b6"
     },
     {
       "id": "release-flow",

package/dist/site/workflow-registry.json

@@ -34,6 +34,7 @@
         "checkout-cache-reference-repository-template",
         "checkout-cache-timeout-seconds",
         "expected-artifacts-json",
+        "gate-profile-aggregate-json",
         "install-command",
         "linux-container-image",
         "linux-container-preset",
@@ -65,7 +66,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 57,
+      "inputCount": 58,
       "surface": "reusable-build",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
@@ -79,6 +80,35 @@
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
+    {
+      "id": ".gate-profile",
+      "path": ".github/workflows/.gate-profile.yml",
+      "inputs": [
+        "artifact-name",
+        "artifact-retention-days",
+        "buildchain-ref",
+        "buildchain-repository",
+        "gate-command-json",
+        "gate-environment-json",
+        "gate-plan-command-json",
+        "gate-profile",
+        "gate-registry",
+        "include-advisory",
+        "node-version",
+        "platforms-json",
+        "require-trusted-event",
+        "runner-preset",
+        "shifu-cache-profile-digest",
+        "shifu-cache-profile-ref",
+        "source-ref",
+        "untrusted-policy",
+        "working-directory"
+      ],
+      "inputCount": 19,
+      "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
+      "status": "active"
+    },
     {
       "id": ".release-docker",
       "path": ".github/workflows/.release-docker.yml",
@@ -384,6 +414,7 @@
         "checkout-cache-reference-repository-template",
         "checkout-cache-timeout-seconds",
         "expected-artifacts-json",
+        "gate-profile-aggregate-json",
         "install-command",
         "linux-container-image",
         "linux-container-preset",
@@ -415,7 +446,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 60,
+      "inputCount": 61,
       "surface": "channel-build-router",
       "capabilityGroup": "reusable-build",
       "status": "active"
@@ -548,12 +579,13 @@
       "inputs": [
         "buildchain-ref",
         "buildchain-repository",
+        "mode",
         "node-version",
         "require-version-state",
         "upload-artifacts",
         "working-directory"
       ],
-      "inputCount": 6,
+      "inputCount": 7,
       "surface": "repository-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"

package/docs/MAP.md

@@ -28,7 +28,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | --- | --- | --- |
 | Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |
 | Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
-| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
+| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
 | Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |
@@ -95,6 +95,7 @@ replace them.
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
 | What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
+| How does Buildchain schedule and aggregate a project-owned Shifu Gate profile? | [`shifu-gate-profiles.md`](shifu-gate-profiles.md) | use/verify | draft |
 | How do I use one build job that follows alpha during development and stable for releases? | [`reusable-build-surface.md`](reusable-build-surface.md#automatic-channel-router) | use | preview |
 | How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |
 | How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |

package/docs/lifecycle-protocol.md

@@ -158,6 +158,9 @@ commands = [
   "pnpm run package",
 ]
 
+[lifecycle.check]
+command = "pnpm run check:source"
+
 [lifecycle.verify]
 shell = "bash"
 script = """
@@ -167,6 +170,19 @@ git diff --check
 """
 ```
 
+`lifecycle.check` is the repository-owned source-acceptance gate. It should
+validate the checked-out source revision without entering the build, artifact,
+or release lifecycle. Consumers can run it on GitHub-hosted Linux through
+`.github/workflows/check.yml@v2` with `mode: source`; the reusable workflow runs
+only `lifecycle.install` and `lifecycle.check`. The default `mode: verify`
+continues to run `lifecycle.install` and `lifecycle.verify` for existing callers.
+Both executed stages receive `BUILDCHAIN_CHECK_MODE=source` or
+`BUILDCHAIN_CHECK_MODE=verify`, so a repository whose normal install path can
+compile native tooling can select a provisioning-only install path for source
+acceptance without weakening promotion installs.
+The reusable job name remains `check`, and `upload-artifacts: false` disables
+evidence upload without changing the job conclusion used by branch protection.
+
 Shared environment variables can be declared once:
 
 ```toml

package/docs/release-governance.md

@@ -412,6 +412,13 @@ Consumers that want Buildchain to own the check wrapper can call
 `lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when
 either declaration is missing or the command exits non-zero.
 
+Development pull requests that need source acceptance without product build or
+artifact verification can opt into `mode: source`. That mode runs only
+`lifecycle.install` and `lifecycle.check` on GitHub-hosted `ubuntu-24.04` while
+preserving the stable `check / check` required-check context. Existing callers
+remain on `mode: verify` by default, and callers may set
+`upload-artifacts: false` without weakening the job conclusion.
+
 Typical consumer wrapper:
 
 ```yaml

package/docs/shifu-gate-profiles.md

@@ -0,0 +1,163 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-shifu-gate-orchestration
+doc_type: technical-manual
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: self-reviewed
+last_reviewed: 2026-07-13
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-13
+  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.
+---
+
+# Shifu Gate profile orchestration
+
+Buildchain can schedule and aggregate a project-owned Shifu Gate profile without
+owning that project's gate ids, commands, dependencies, or dev/alpha/release
+policy. The reusable workflow is
+`.github/workflows/.gate-profile.yml`.
+
+## Ownership boundary
+
+| Concern                                                                             | Owner                                 | Enforced surface                                                             |
+| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
+| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |
+| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |
+| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |
+| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |
+| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |
+
+Buildchain treats the Shifu plan and receipt as versioned input contracts. It
+does not reimplement policy selection, execute raw shell strings, convert an
+explicit diagnostic gate run into qualification, or mint missing evidence.
+
+## Runner matrix
+
+The plan job asks the consumer's Shifu entrypoint for one plan per configured
+platform. A platform is dispatchable only when:
+
+- the Shifu plan is qualifying;
+- every required selection is supported on that platform;
+- the runner declares every capability requested by the selected gates; and
+- all platform plans carry the same project id and registry digest.
+
+Configured platforms are required by default. A required platform that cannot
+host the profile fails before runner dispatch. A platform with
+`"required": false` may be omitted, but the omission and reasons remain in the
+matrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate
+groups, required/advisory modes, action ids, definition digests, skips, and
+unsupported selections.
+
+`github-hosted` declares only the inherent `node` capability. Projects that
+need a native compiler, product artifacts, devices, or other facilities must
+use a suitable preset or declare a custom matrix. Capabilities are scheduling
+claims, not installation instructions.
+
+```json
+[
+  {
+    "id": "linux-native",
+    "name": "Linux native",
+    "platform": "linux",
+    "runner": "[\"self-hosted\",\"Linux\",\"X64\",\"product-build\"]",
+    "capabilities": ["node", "native-toolchain", "product-artifacts"]
+  }
+]
+```
+
+## Execution and receipts
+
+Every matrix job checks out the exact source SHA planned by Buildchain, invokes
+`shifu gate run --profile`, writes the receipt outside the source checkout, and
+then invokes `shifu gate receipt validate`. Buildchain uploads the original
+receipt and validation result even when the run fails.
+
+The fixed `Gate profile / aggregate` job fails closed for missing receipts,
+invalid or stale Shifu validation, dirty or mismatched source SHA, registry or
+plan drift, missing required results, required failures/skips, or gate action
+and definition digest drift. Advisory failures remain visible but do not turn a
+Shifu-qualifying receipt into a required failure. Buildchain's aggregate is
+`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,
+per-gate evidence pointers, omissions, and issues.
+
+## Consumer workflow
+
+```yaml
+jobs:
+  gates:
+    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v2
+    with:
+      gate-profile: alpha-pr
+      runner-preset: kungfu-v4-self-hosted
+      include-advisory: true
+
+  build:
+    needs: gates
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    with:
+      release-candidate: true
+      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}
+```
+
+The command input is an argv map, not a shell string. The default supports the
+ordinary Shifu launcher names on all three platforms. A project with a
+different launcher can override it without teaching Buildchain project tasks:
+
+```yaml
+gate-command-json: >-
+  {"linux":["./tools/shifu"],"macos":["./tools/shifu"],"windows":["./tools/shifu.cmd"]}
+```
+
+`gate-command-json` is the execution command. If execution needs a cache,
+container, or other project-owned wrapper that should not make the read-only
+plan depend on that service, pass a separate lightweight argv map through
+`gate-plan-command-json`. It defaults to the execution command for backward
+compatibility; Buildchain still treats both inputs as argv and never evaluates
+a shell string.
+
+Projects may also pass non-sensitive scalar environment through
+`gate-environment-json`; Buildchain validates the JSON shape and forwards it
+without interpreting names or values. Cache profile references use the same
+opaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the
+reusable build. Do not place tokens, credentials, or other secrets in workflow
+inputs or Gate receipts.
+
+When a qualifying aggregate is passed to the build workflow, the
+release-candidate passport binds its profile, source SHA, registry digest,
+matrix digest, aggregate digest, receipt count, and result count. A failed,
+non-qualifying, or source-mismatched aggregate cannot produce a valid passport.
+Promote-only release validation preserves that same Gate evidence summary in
+the final Release Passport release identity, so promotion cannot silently drop
+the qualified profile provenance.
+
+## Failure diagnosis and rollback
+
+Start with the aggregate artifact, then the platform receipt named in its
+issues. Reproduce the exact project decision with Shifu, for example:
+
+```bash
+./shifu gate explain <gate-id> --profile <profile>
+./shifu gate plan <profile> --platform <platform> --json
+./shifu gate receipt validate <receipt.json> --json
+```
+
+The existing reusable build workflow remains usable without Gate inputs. To
+roll back Gate orchestration, remove the caller's `gates` job and
+`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu
+registry or its direct diagnostic commands.
+
+## Validation boundary
+
+Unit fixtures prove deterministic matrix generation and required/advisory,
+capability, unsupported, missing, stale, failure, and definition-drift
+propagation. Because a train ref changes runtime scripts but not the outer
+reusable workflow topology, an unreleased `.gate-profile.yml` must also be
+validated through a trusted `workflow_dispatch` canary that references the
+temporary workflow ref or exact SHA. See
+[`runtime-train-validation.md`](runtime-train-validation.md).

package/docs/stable-candidate-patrol.md

@@ -122,15 +122,35 @@ jobs:
       dry-run: false
     secrets:
       promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}
 ```
 
 The promotion token must be repository-owned and capable of creating the
 machine ledger branch, exact source-lock branch, and pull request. Repositories
-that require an approving review can set `auto-approve: true` only when their
-GitHub Actions policy explicitly allows the caller token to approve the PR;
-otherwise a repository-owned App or review bot supplies the approval. The
+that require an approving review can pass an independent repository-owned App,
+bot, or human service-account token as `approval-token`. The approval identity
+must differ from the promotion token identity that opens the PR. When no
+`approval-token` is passed, `auto-approve: true` falls back to the caller
+`github.token` and therefore requires GitHub Actions approval permission. The
 generated PR may use auto-merge, but it never bypasses the target branch checks.
 
+Before enabling `auto-approve` and `auto-merge`, the caller repository must
+provide one approval path and enable auto-merge:
+
+- pass an independent `approval-token`; or enable **Actions > General >
+  Workflow permissions > Allow GitHub Actions to create and approve pull
+  requests**, so the caller `github.token` can approve independently from the
+  promotion token that opened the PR;
+- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the
+  protected merge while required reviews and checks are still pending.
+
+GitHub rejects approval from the same identity that opened the pull request;
+Patrol propagates that review failure instead of reporting success.
+
+Patrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run
+must not report publication authority when GitHub accepted the HTTP request but
+returned a GraphQL error in the response body.
+
 ## Exact-source stable promotion
 
 For a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:

package/package.json

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

package/packages/core/release-candidate.js

@@ -100,6 +100,36 @@ function inferVersionFromReleaseManifest(buildSummary = {}) {
   }
 }
 
+function normalizeGateProfileEvidence(gateAggregate = undefined) {
+  if (gateAggregate === undefined || gateAggregate === null || gateAggregate === "") return undefined;
+  if (!gateAggregate || typeof gateAggregate !== "object" || Array.isArray(gateAggregate)) {
+    throw new Error("gateAggregate must be an object");
+  }
+  if (gateAggregate.contract !== "buildchain.shifu-gate-aggregate/v1") {
+    throw new Error("gateAggregate must use buildchain.shifu-gate-aggregate/v1");
+  }
+  const { digest, ...digestInput } = gateAggregate;
+  const expectedDigest = `sha256:${sha256Json(digestInput)}`;
+  if (digest !== expectedDigest) {
+    throw new Error("gateAggregate digest does not match its content");
+  }
+  return {
+    contract: gateAggregate.contract,
+    digest,
+    profile: nonEmptyString(gateAggregate.profile, "gateAggregate.profile"),
+    sourceSha: nonEmptyString(gateAggregate.sourceSha, "gateAggregate.sourceSha"),
+    registry: {
+      projectId: nonEmptyString(gateAggregate.registry?.projectId, "gateAggregate.registry.projectId"),
+      digest: nonEmptyString(gateAggregate.registry?.digest, "gateAggregate.registry.digest"),
+    },
+    matrixDigest: nonEmptyString(gateAggregate.matrixDigest, "gateAggregate.matrixDigest"),
+    status: nonEmptyString(gateAggregate.status, "gateAggregate.status"),
+    qualifying: gateAggregate.qualifying === true,
+    receiptCount: Array.isArray(gateAggregate.receipts) ? gateAggregate.receipts.length : 0,
+    gateResultCount: Array.isArray(gateAggregate.gates) ? gateAggregate.gates.length : 0,
+  };
+}
+
 export function createReleaseCandidatePassport({
   repository = "",
   pullRequest = {},
@@ -111,6 +141,7 @@ export function createReleaseCandidatePassport({
   sourceTreeHash = "",
   buildSummary = {},
   buildchain = {},
+  gateAggregate = undefined,
   workflow = {},
   createdAt = nowIso(),
 } = {}) {
@@ -122,6 +153,7 @@ export function createReleaseCandidatePassport({
     || normalizeTargetChannel(normalizedSummary.publishGate?.channel)
     || normalizeTargetChannel(pullRequest.baseRef);
   const resolvedVersion = version || normalizedSummary.publishSource?.consumerVersion || inferVersionFromReleaseManifest(normalizedSummary);
+  const gateProfileEvidence = normalizeGateProfileEvidence(gateAggregate);
   const candidate = {
     schemaVersion: 1,
     contract: RELEASE_CANDIDATE_PASSPORT_CONTRACT,
@@ -164,6 +196,7 @@ export function createReleaseCandidatePassport({
       buildSummaryContract: optionalString(normalizedSummary.contract),
       buildSummaryHash: sha256Json(normalizedSummary),
     },
+    ...(gateProfileEvidence ? { gateProfileEvidence } : {}),
   };
   candidate.candidateHash = sha256Json({
     repository: candidate.repository,
@@ -171,6 +204,7 @@ export function createReleaseCandidatePassport({
     source: candidate.source,
     platformMatrix: candidate.platformMatrix,
     buildchain: candidate.buildchain,
+    ...(candidate.gateProfileEvidence ? { gateProfileEvidence: candidate.gateProfileEvidence } : {}),
   });
   return candidate;
 }
@@ -225,5 +259,13 @@ export function validateReleaseCandidatePassport({
     const expectedHash = sha256Json(buildSummary);
     check(passport.diagnostics?.buildSummaryHash === expectedHash, "build summary hash mismatch");
   }
+  if (passport.gateProfileEvidence) {
+    check(passport.gateProfileEvidence.contract === "buildchain.shifu-gate-aggregate/v1", "gate profile evidence contract mismatch");
+    check(passport.gateProfileEvidence.sourceSha === passport.source?.headSha, "gate profile evidence source SHA mismatch");
+    check(passport.gateProfileEvidence.status === "pass", "gate profile evidence status must be pass");
+    check(passport.gateProfileEvidence.qualifying === true, "gate profile evidence must be qualifying");
+    check(Boolean(passport.gateProfileEvidence.digest), "gate profile evidence digest is required");
+    check(Boolean(passport.gateProfileEvidence.matrixDigest), "gate profile matrix digest is required");
+  }
   return { ok: errors.length === 0, errors };
 }