@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/AGENTS.md

@@ -23,7 +23,7 @@ override that policy:
 uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3
 ```
 
-During the v2.12 alpha evaluation window, canaries call the same router through
+During v3 prerelease evaluation windows, canaries call the same router through
 the matching prerelease ref:
 
 ```yaml

package/CONTRIBUTING.md

@@ -120,7 +120,7 @@ release/vX/vX.Y -> publish-gate/major
   branch prefixes, max merges, and dry-run are all declared inputs.
 - When a Buildchain change needs downstream validation before stable refs move,
   publish a temporary runtime train ref such as
-  `train/v2/v2.3/<capability>` and ask consumers to run trusted
+  `train/v3/v3.0/<capability>` and ask consumers to run trusted
   `workflow_dispatch` with `buildchain-ref` set to that train. Keep the pull
   request against the `dev/*` branch; the train is only a validation pointer,
   not a pending merge target. After validation succeeds, merge into the active

package/README.md

@@ -191,6 +191,22 @@ npx @kungfu-tech/buildchain validate --require-version-state
 npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0
 ```
 
+Bootstrap and inspect a governed paper repository through one interface:
+
+```bash
+npx @kungfu-tech/buildchain paper scaffold \
+  --package @kungfu-tech/paper-example \
+  --repository kungfu-systems/paper-example
+npx @kungfu-tech/buildchain paper preflight --offline
+npx @kungfu-tech/buildchain paper status
+```
+
+The paper surface is dry-run first. Add `--write` only to create missing
+scaffold files; external mutations such as npm bootstrap, Alpha PR creation,
+and release resumption require `--execute`. See
+[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the
+evidence-state model and operator flow.
+
 Buildchain supports package and non-package projects through
 `.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain
 readable, but new consumers should keep Buildchain-owned files under
@@ -212,13 +228,23 @@ plus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These
 gates preserve product-owned qualification and support decisions; they do not
 turn a schema-valid record into certification or shipped support.
 
-Buildchain's active GitHub Action surface is deliberately small:
+Buildchain's action registry currently contains six active entries. Four are
+direct consumer integration actions:
 
 - `actions/validate-config`
 - `actions/run-lifecycle`
 - `actions/promote-buildchain-ref`
 - `actions/report-buildchain-issue`
 
+Two additional release-authority components are also registered and versioned:
+
+- `actions/github-artifact-attestation`
+- `actions/macos-credential-island`
+
+`dist/site/workflow-registry.json#actions` is the machine-readable inventory;
+this split keeps the older four-action consumer list from being mistaken for
+the complete current registry.
+
 The active reusable workflow surfaces are:
 
 - `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile

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

@@ -1,28 +1,46 @@
+---
+status: active
+period: ongoing
+theme: buildchain-ref-promotion-action
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # promote-buildchain-ref
 
 Internal buildchain action for promoting verified buildchain release-line and
 compatibility refs from buildchain release channels:
 
-- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as
-  `v2.0.1-alpha.0`, writes that version into package version state, points the
+- `alpha/v3/v3.0` creates or reuses the next exact prerelease tag such as
+  `v3.0.3-alpha.0`, writes that version into package version state, points the
   alpha and dev channel branches at the version commit, then promotes
-  `v2.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;
-- `release/v2/v2.0` creates or reuses the next exact release tag such as
-  `v2.0.0`, writes that version into package version state, points the release
+  `v3.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;
+- `release/v3/v3.0` creates or reuses the next exact release tag such as
+  `v3.0.2`, writes that version into package version state, points the release
   channel branch and release tags at the release commit, then prepares a second
-  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and
-  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease
-  commit, and moves `v3-alpha` only if no higher v2 minor has published an alpha;
+  source commit for the next exact prerelease tag such as `v3.0.3-alpha.0` and
+  points the alpha/dev channel branches plus `v3.0-alpha` at that prerelease
+  commit, and moves `v3-alpha` only if no higher v3 minor has published an alpha;
 - `publish-gate/major` accepts a reviewed PR from a production release line such
-  as `release/v2/v2.0`, writes the next major production version such as
-  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`
-  at that release commit, then prepares `v3.0.1-alpha.0` for
-  `alpha/v3/v3.0`, `dev/v3/v3.0`, `v3.0-alpha`, and `v3-alpha`. The older `major-gate`
+  as `release/v3/v3.0`, writes the next major production version such as
+  `v4.0.0`, points `publish-gate/major`, `release/v4/v4.0`, `v4.0`, and `v4`
+  at that release commit, then prepares `v4.0.1-alpha.0` for
+  `alpha/v4/v4.0`, `dev/v4/v4.0`, `v4.0-alpha`, and `v4-alpha`. The older `major-gate`
   branch name is a compatibility alias only.
 
 The release branch name defines the minor line. For example,
-`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only
-when the next minor tag such as `v2.2` does not already exist.
+`release/v3/v3.1` creates `v3.1.N`, promotes `v3.1`, and promotes `v3` only
+when the next minor tag such as `v3.2` does not already exist.
 
 The action updates version state in `lerna.json`, root `package.json`, and
 workspace package manifests discovered from package manager metadata
@@ -134,7 +152,7 @@ trusted channel workflow:
     token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
     generated-ref-update-token: ${{ github.token }}
     sha: ${{ github.sha }}
-    target-ref: release/v2/v2.0
+    target-ref: release/v3/v3.0
     publish-transaction: "true"
     publish-mode: publish-final-version
     publish-auth: trusted-publishing
@@ -219,6 +237,10 @@ and fail before publish-gate side effects if it no longer matches:
     promote-only-release-candidate: "true"
     release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json
     release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json
+    release-candidate-family-evidence-required: "true"
+    release-candidate-family-evidence-root: sha256:<initiative-family-root>
+    release-candidate-family-initiative-id: 2026-07-30-example-initiative
+    release-candidate-family-assignment-id: 2026-07-30-example-release
 ```
 
 The action validates repository, channel, source identity, platform matrix, and
@@ -229,6 +251,14 @@ channel HEAD's Git tree SHA matching the passport tree hash. If validation
 fails, run or attach the verified channel PR build first instead of promoting a
 stale or unproven artifact set.
 
+The four family-evidence inputs are optional. When enabled, the action requires
+the candidate passport to carry the exact
+`kungfu-buildchain-initiative-family-release-evidence/v1` envelope and checks
+its family root, Initiative id, and Assignment id before any promotion
+mutation. Buildchain only transports and validates this adapter-edge release
+evidence; Kungfu Work Control remains authoritative for native Family State v1
+and its additive v2 typed envelope.
+
 When enabled, the action creates or resumes a release transaction keyed by
 repository, version, source SHA, and target ref. It persists that transaction to
 a machine-managed branch under `buildchain/release-state/<version>`, with
@@ -244,6 +274,16 @@ Passport collection. This is explicit opt-in because registry publication and
 other provider mutations must not be replayed blindly; the option rejects
 `promote-existing-version`.
 
+Build-once callers additionally pass `publish-sealed-bundle-root` and
+`publish-sealed-bundle-manifest`. The action verifies the typed manifest and
+persists every declared file below
+`sealed-bundle/<candidate-root>/files/` on the same durable ref before it starts
+the publish command. A fresh runner can omit both inputs: the action restores
+the exact binary bundle into `.buildchain/recovered-publication/<version>/`,
+re-verifies it, and exports the recovered npm tarball through
+`BUILDCHAIN_SEALED_NPM_TARBALL` with its exact integrity and SHA-256. This path
+never repacks the npm tarball.
+
 The action runs `lifecycle.publish` from `buildchain.toml` or the explicit
 `publish-command` input, then validates publish evidence before exact tags and
 floating refs move. If durable state persistence fails, the action fails closed
@@ -275,6 +315,10 @@ BUILDCHAIN_RELEASE_SHA
 BUILDCHAIN_RELEASE_MATERIAL_SHA
 BUILDCHAIN_PUBLISH_TOOLING_SHA
 BUILDCHAIN_PUBLISH_EVIDENCE
+BUILDCHAIN_SEALED_BUNDLE_ROOT
+BUILDCHAIN_SEALED_NPM_TARBALL
+BUILDCHAIN_SEALED_NPM_INTEGRITY
+BUILDCHAIN_SEALED_NPM_SHA256
 BUILDCHAIN_REQUIRED_ARTIFACTS
 ```
 
@@ -287,11 +331,17 @@ before `lifecycle.publish`. Requirement descriptors may omit `digest`; final
 publish evidence may not.
 
 The action outputs `transaction-id`, `transaction-state`,
+`transaction-publication-state`, `transaction-sealed-bundle-root`,
+`transaction-resume-command`,
 `transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,
 `transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,
 `publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,
 `release-passport-state-sha`, and `finalization-needed`.
 `transaction-state-ref` is the durable recovery location.
+`transaction-publication-state` provides the stable
+`prepared`, `sealed`, `package-published`, `alpha-complete`, or
+`release-complete` operator view. `transaction-resume-command` is the exact
+consumer-facing resume entrypoint bound into the sealed manifest.
 `release-passport-state-sha` is the durable ref commit after the generated
 `release-passport/*` files have been uploaded into that recovery ref.
 `finalization-needed=true` means publish evidence is valid, but protected branch
@@ -311,7 +361,11 @@ package releases, `public-release-tag` is derived
 from the published package version, while `transaction-exact-tag` remains the
 internal Buildchain transaction ref for recovery and audit. If the transaction is
 not complete yet, the action defers GitHub Release publication to the next
-idempotent promotion run.
+idempotent promotion run. When sealed release assets are present, those restored
+files replace caller-supplied artifact paths. After upload succeeds, the action
+writes the `github_release` milestone back to the durable transaction; an
+interruption before that write is safe to retry because release creation and
+asset replacement are idempotent.
 
 After a publish transaction reaches `complete`, the action generates the unified
 `buildchain-release-passport` in `.buildchain/release-passport` by default and
@@ -351,6 +405,23 @@ requires a `verified` verdict, complete platform coverage, a clean exact source
 revision, and then binds the result into `buildchain.release.json`. Missing,
 stale, falsified, incomplete, dirty, or tampered Passport evidence fails the
 release transaction closed.
+Set `release-passport-evidence-jsons` to newline-separated product-owned release
+evidence attachment indexes. Each JSON document must declare `schemaVersion`, a
+stable `id`, a product contract, and the exact release source SHA, tag, and
+channel. Buildchain copies and hashes the documents, verifies their coordinates
+against the final Passport, and retains them in the release evidence bundle
+without interpreting product-specific or legal claims.
+
+When release coordinates are not known until promotion, set
+`release-passport-attachment-command`. Buildchain supplies
+`BUILDCHAIN_RELEASE_SOURCE_SHA`, `BUILDCHAIN_RELEASE_TAG`,
+`BUILDCHAIN_RELEASE_CHANNEL`, `BUILDCHAIN_RELEASE_VERSION`,
+`BUILDCHAIN_RELEASE_DEPLOYMENT_COORDINATE`, `BUILDCHAIN_RELEASE_TARGET_REF`, and
+`BUILDCHAIN_RELEASE_PASSPORT_OUTPUT_DIR`; the command must emit a JSON array or
+an object with a non-empty `files` array. Direct Action callers may still use
+the v2 alias `release-passport-evidence-command`. Reusable v3 workflows reserve
+that older name for the distinct post-activation released-evidence command.
+
 Buildchain's own release workflow sets `release-passport-buildchain-self-kfd:
 "true"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses
 inside the final version-state workspace, after the release transaction has
@@ -446,15 +517,15 @@ so the mutation path cannot widen the authority descriptor.
 
 The tag names intentionally follow the old ABV release semantics:
 exact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating
-release tags are minor/major tags such as `v2.0` and `v2`, and floating alpha
-tags are minor-line tags such as `v2.0-alpha` plus cross-minor major tags such
+release tags are minor/major tags such as `v3.0` and `v3`, and floating alpha
+tags are minor-line tags such as `v3.0-alpha` plus cross-minor major tags such
 as `v3-alpha`. A major alpha tag only moves for the highest minor in that major
 with a published alpha, so older-line maintenance cannot roll consumers back.
 Bare tags such as `1.0.0` are not
 maintained as buildchain release entrypoints.
 
 Repository rulesets should protect exact tags, not every `v*` tag. A ruleset
-such as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha` and `v3-alpha`,
+such as `refs/tags/v*` also protects floating channel tags like `v3.0-alpha` and `v3-alpha`,
 which Buildchain must update after exact tags and publish evidence are durable.
 Use an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and
 leave floating channel tags mutable for the promotion token.

package/actions/report-buildchain-issue/README.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-consumer-issue-action
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # report-buildchain-issue
 
 Create or update a Buildchain repository issue from a consumer workflow or from
@@ -25,7 +43,7 @@ organization.
     token: ${{ steps.buildchain-issue-token.outputs.token }}
     summary: "Reusable build failed before artifact finalization"
     failure-code: reusable-build-failed
-    buildchain-ref: ${{ inputs.buildchain-ref || 'v2' }}
+    buildchain-ref: ${{ inputs.buildchain-ref || 'v3' }}
     diagnostics-path: .buildchain/artifacts/diagnostics.json
 ```
 
@@ -76,7 +94,7 @@ steps:
       workflow: ${{ github.workflow }}
       run-id: ${{ github.run_id }}
       run-attempt: ${{ github.run_attempt }}
-      channel: alpha/v2/v2.4
+      channel: alpha/v3/v3.0
       source-sha: ${{ github.sha }}
       friction-class: duplicate-build
       related-runs-json: ${{ steps.classify.outputs.related-runs-json }}

package/actions/run-lifecycle/README.md

@@ -26,6 +26,11 @@ be diagnosed after the runner is released.
 The action writes both a full manifest and a compact summary. It also exposes
 the summary as outputs for reusable workflow callers:
 
+For a `build` stage, paths selected by `[[signing.artifacts]]` for the current
+`platform-id` are automatically included in the lifecycle manifest even when
+they sit outside `artifact-paths`. This binds every byte sent to the signing
+authority without changing which ordinary product paths the caller uploads.
+
 | Output | Meaning |
 | --- | --- |
 | `manifest-path` | Full manifest path |

package/actions/validate-config/README.md

@@ -1,6 +1,24 @@
+---
+status: active
+period: ongoing
+theme: buildchain-config-validation-action
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # validate-config
 
-Buildchain v2 action for validating `buildchain.toml` without running lifecycle
+Buildchain v3 action for validating `.buildchain/buildchain.toml` without running lifecycle
 commands.
 
 Use this action during repository migration when a heavyweight project needs to

package/bin/buildchain.mjs

@@ -11,6 +11,8 @@ import { runReleasePropagationCli } from "../scripts/release-propagation.mjs";
 import { runReleaseGovernanceCli } from "../scripts/reconcile-release-governance.mjs";
 import { runPublicationArtifactCli } from "../scripts/publication-artifact.mjs";
 import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
+import { runPublicationReproducibilityCli } from "../scripts/publication-reproducibility.mjs";
+import { runPaperCli } from "../scripts/paper.mjs";
 import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
 import { detectPackageManager } from "../packages/core/package-manager.js";
 import {
@@ -99,9 +101,14 @@ import {
   TRUST_RELEASE_COMMANDS,
   dispatchTrustReleaseCommand,
 } from "./internal/trust-release-cli.mjs";
+import {
+  BUILDCHAIN_COMMAND_REGISTRY,
+  dispatchRegisteredCommand,
+} from "./internal/command-registry.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
+const embeddedSourceSha = process.env.BUILDCHAIN_EMBEDDED_SOURCE_SHA || "";
 
 function usage() {
   return `Usage:
@@ -164,6 +171,7 @@ function usage() {
                                     [--kfd-product-gate-json <json-or-path>]...
                                     [--invariant-passport-json <json-or-path>]...
                                     [--invariant-passport-cmd <command>]
+                                    [--release-evidence-json <json-or-path>]...
                                     [--github-artifact-attestation-policy-json <json-or-path>]...
                                     [--kfd-agent-hub-evidence-json <json-or-path>]
                                     [--base-passport-json <json-or-path>] [--require-base-kfd]
@@ -294,6 +302,20 @@ function usage() {
                                            [--registry-output <file>] [--source-bundle <file>]
                                            [--no-source-bundle] [--json]
   buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]
+  buildchain publication-artifact reproducibility [--cwd <dir>] [--source-sha <sha>]
+                                                   [--output <file>] [--promote]
+                                                   [--no-toolchain-pull]
+                                                   [--allow-unpinned-toolchain] [--json]
+  buildchain paper scaffold --package <name> --repository <owner/repo> [--write] [--json]
+  buildchain paper migrate [--cwd <dir>] [--write] [--json]
+  buildchain paper preflight [--cwd <dir>] [--offline] [--json]
+  buildchain paper bootstrap npm [--cwd <dir>] [--execute]
+                                  [--confirm-public-package <name>] [--json]
+  buildchain paper build [--cwd <dir>] [--execute] [--json]
+  buildchain paper alpha [--cwd <dir>] [--source-ref <ref>] [--target-ref <ref>]
+                          [--execute] [--json]
+  buildchain paper status [--cwd <dir>] [--json]
+  buildchain paper resume [--cwd <dir>] [--buildchain-ref <ref>] [--execute] [--json]
   buildchain release-propagation <plan|write-lock> ...
   buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
   buildchain badges bundle [--cwd <dir>] [--readme <path>] [--claims <csv>] [--check] [--write] [--json]
@@ -329,6 +351,8 @@ Examples:
   buildchain infra-contract --mode propagation-apply --propagation-plan <plan.json> --dry-run true
   buildchain infra-contract --mode evidence-bundle --artifact <artifact.json> --propagation-result <result.json>
   buildchain publication-artifact manifest --source-sha <sha> --json
+  buildchain paper preflight --json
+  buildchain paper status --json
   buildchain release-propagation plan --graph graph.json --upstream-release release.json --json
   buildchain kfd status --json
   buildchain kfd schema list --json
@@ -1456,8 +1480,7 @@ async function runProcessTreeSample(sampleArgs = []) {
   return report;
 }
 
-async function main(argv = process.argv.slice(2)) {
-  const [command, ...args] = argv;
+async function runRegisteredCommand(command, args) {
   if (!command || command === "-h" || command === "--help" || command === "help") {
     process.stdout.write(usage());
     return;
@@ -1814,10 +1837,25 @@ async function main(argv = process.argv.slice(2)) {
       runPublicationPackageCli(args.slice(1));
       return;
     }
+    if (args[0] === "reproducibility" || args[0] === "reproducible") {
+      runPublicationReproducibilityCli(args.slice(1));
+      return;
+    }
     runPublicationArtifactCli(args);
     return;
   }
 
+  if (command === "paper") {
+    await runPaperCli(args, {
+      buildchainRoot: root,
+      buildchainVersion: packageVersion(),
+      buildchainRef: process.env.BUILDCHAIN_RUNTIME_REF || "v3",
+      buildchainSha:
+        process.env.BUILDCHAIN_RUNTIME_SHA || embeddedSourceSha || "",
+    });
+    return;
+  }
+
   if (command === "release-propagation") {
     runReleasePropagationCli(args);
     return;
@@ -1886,6 +1924,22 @@ async function main(argv = process.argv.slice(2)) {
   throw new Error(`unsupported buildchain command: ${command}`);
 }
 
+const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze(Object.fromEntries(
+  BUILDCHAIN_COMMAND_REGISTRY.map((entry) => [
+    entry.id,
+    (args) => runRegisteredCommand(entry.id, args),
+  ]),
+));
+
+async function main(argv = process.argv.slice(2)) {
+  const [command = "help", ...args] = argv;
+  return dispatchRegisteredCommand({
+    command,
+    args,
+    handlers: BUILDCHAIN_COMMAND_HANDLERS,
+  });
+}
+
 main().catch((error) => {
   console.error(`buildchain: ${error.message}`);
   process.exitCode = 1;

package/bin/internal/command-registry.mjs

@@ -0,0 +1,82 @@
+const BUILDCHAIN_COMMAND_REGISTRY = Object.freeze([
+  { id: "help", aliases: ["-h", "--help"] },
+  { id: "version", aliases: ["-v", "--version"] },
+  { id: "layout", aliases: [] },
+  { id: "portable-cache", aliases: [] },
+  { id: "candidate", aliases: [] },
+  { id: "init", aliases: [] },
+  { id: "validate", aliases: [] },
+  { id: "doctor", aliases: [] },
+  { id: "dev", aliases: [] },
+  { id: "log", aliases: [] },
+  { id: "diagnostics", aliases: [] },
+  { id: "facts", aliases: [] },
+  { id: "kfd", aliases: [] },
+  { id: "sample", aliases: [] },
+  { id: "mark", aliases: [] },
+  { id: "span", aliases: [] },
+  { id: "lifecycle", aliases: [] },
+  { id: "npm", aliases: [] },
+  { id: "audit", aliases: [] },
+  { id: "collect", aliases: [] },
+  { id: "create", aliases: [] },
+  { id: "explain", aliases: [] },
+  { id: "inspect", aliases: [] },
+  { id: "project", aliases: [] },
+  { id: "release", aliases: [] },
+  { id: "transaction", aliases: [] },
+  { id: "verify", aliases: [] },
+  { id: "web-surface", aliases: [] },
+  { id: "infra-contract", aliases: [] },
+  { id: "publication-artifact", aliases: ["publication"] },
+  { id: "paper", aliases: [] },
+  { id: "release-propagation", aliases: [] },
+  { id: "release-governance", aliases: [] },
+  { id: "github-governance", aliases: [] },
+  { id: "badges", aliases: [] },
+  { id: "homebrew", aliases: [] },
+  { id: "build-contract", aliases: [] },
+  { id: "publish-source", aliases: [] },
+]);
+
+function buildCommandLookup(registry = BUILDCHAIN_COMMAND_REGISTRY) {
+  const lookup = new Map();
+  for (const entry of registry) {
+    for (const name of [entry.id, ...entry.aliases]) {
+      if (lookup.has(name)) {
+        throw new Error(
+          `duplicate Buildchain CLI command registration: ${name}`,
+        );
+      }
+      lookup.set(name, entry);
+    }
+  }
+  return lookup;
+}
+
+const BUILDCHAIN_COMMAND_LOOKUP = buildCommandLookup();
+
+function resolveBuildchainCommand(command) {
+  return BUILDCHAIN_COMMAND_LOOKUP.get(command || "help");
+}
+
+async function dispatchRegisteredCommand({ command, args = [], handlers }) {
+  const registration = resolveBuildchainCommand(command);
+  if (!registration) {
+    throw new Error(`unsupported buildchain command: ${command}`);
+  }
+  const handler = handlers?.[registration.id];
+  if (typeof handler !== "function") {
+    throw new Error(
+      `Buildchain CLI command has no registered handler: ${registration.id}`,
+    );
+  }
+  return handler(args, { command, registration });
+}
+
+export {
+  BUILDCHAIN_COMMAND_REGISTRY,
+  buildCommandLookup,
+  dispatchRegisteredCommand,
+  resolveBuildchainCommand,
+};

package/bin/internal/trust-release-cli.mjs

@@ -202,6 +202,7 @@ async function dispatchTrustReleaseCommand({ command, args, runScript, packageVe
       kfdProductGateJsons: readRepeatedFlag(collectArgs, "kfd-product-gate-json"),
       invariantPassportJsons: readRepeatedFlag(collectArgs, "invariant-passport-json"),
       invariantPassportCommand: readFlag(collectArgs, "invariant-passport-cmd", ""),
+      releaseEvidenceJsons: readRepeatedFlag(collectArgs, "release-evidence-json"),
       githubArtifactAttestationPolicyJsons: readRepeatedFlag(
         collectArgs,
         "github-artifact-attestation-policy-json",