@kungfu-tech/buildchain 2.14.2-alpha.0 → 2.14.2

package/dist/site/publication-authority-registry.json

@@ -280,6 +280,19 @@
       "runnerPolicy": "unqualified",
       "notes": ""
     },
+    {
+      "workflowPath": ".github/workflows/dev-merge-queue-governance.yml",
+      "authorityClass": "governance-write",
+      "publicationCapable": false,
+      "capabilityIds": [],
+      "credentialMode": "none",
+      "publisherWorkflowMode": "fixed",
+      "publisherWorkflowPath": ".github/workflows/dev-merge-queue-governance.yml",
+      "environment": "",
+      "environmentMode": "fixed",
+      "runnerPolicy": "unqualified",
+      "notes": ""
+    },
     {
       "workflowPath": ".github/workflows/dev-pr-auto-merge.yml",
       "authorityClass": "governance-write",
@@ -657,6 +670,11 @@
       "signals": [],
       "classified": false
     },
+    {
+      "path": ".github/workflows/dev-merge-queue-governance.yml",
+      "signals": [],
+      "classified": true
+    },
     {
       "path": ".github/workflows/dev-pr-auto-merge.yml",
       "signals": [
@@ -774,5 +792,5 @@
       "classified": false
     }
   ],
-  "registryDigest": "760215fb39e6c85890c925e924c538a766d78abd6319794c8799fb47c23dec3d"
+  "registryDigest": "24c7f5210da277b79ce13356c439c14ea49f6c54ba9e083f42ce47fdfdacc55c"
 }

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-17T02:13:15.755Z",
-  "publishedAt": "2026-07-17T02:13:15.755Z",
+  "generatedAt": "2026-07-18T01:00:00.995Z",
+  "publishedAt": "2026-07-18T01:00:00.995Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "dd861c4e31186a2b68ee4d624bea517757b1e2e2",
+  "sourceRevision": "ae16e640bf2f21c8f981ffa8b3523c8aae9200b2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.2-alpha.0",
+    "version": "2.14.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-17T02:13:15.755Z",
-  "publishedAt": "2026-07-17T02:13:15.755Z",
+  "generatedAt": "2026-07-18T01:00:00.995Z",
+  "publishedAt": "2026-07-18T01:00:00.995Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "dd861c4e31186a2b68ee4d624bea517757b1e2e2",
+  "sourceRevision": "ae16e640bf2f21c8f981ffa8b3523c8aae9200b2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.2-alpha.0",
+    "version": "2.14.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -189,7 +189,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:9ecf8c220b5ff02ee5719cb877d4b2b159c3d683af288630eae0013d9d906373"
+      "digest": "sha256:1733f9377938a16e6de77511546be7de67c5ab8816220d693fd46f55450a5148"
     },
     {
       "id": "build-facts",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:511d214a8d9a24125f64c5cb363aeeb3351a1236eec96f5fa6f49832d5fcba98"
+      "digest": "sha256:e64ffd6183eaa7b73f8c0c133a645ced22212bca70c9609ad5f667cf3830aaae"
     },
     {
       "id": "release-flow",
@@ -245,7 +245,7 @@
       "path": "docs/release-flow.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:a2f68d42f34acc35940e135285df5ba510d91b15b9d9ede8cabbe8bfa6ab0305"
+      "digest": "sha256:fc6495a7b5124c17c880777e16fc98e60ed7766ec9a958abfca3030bdc2c321e"
     },
     {
       "id": "runtime-train-validation",
@@ -261,7 +261,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:c3dce313b846fb36c69e4a725d086226ff2e875c376cc10e8554a0aff2f67c93"
+      "digest": "sha256:e856ec8aee11ff4bd2760425a8950538a91245cd5624c22c8768af50d6b1a8ce"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -992,6 +992,20 @@
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
+    {
+      "id": "dev-merge-queue-governance",
+      "path": ".github/workflows/dev-merge-queue-governance.yml",
+      "reusable": false,
+      "inputs": [],
+      "inputCount": 0,
+      "secrets": [],
+      "secretCount": 0,
+      "outputs": [],
+      "outputCount": 0,
+      "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
+      "status": "active"
+    },
     {
       "id": "dev-pr-auto-merge",
       "path": ".github/workflows/dev-pr-auto-merge.yml",

package/docs/cli.md

@@ -208,6 +208,31 @@ required status checks from strict to loose, preserves the required check
 identities, and is safe to repeat. `gh` must be authenticated with repository
 Administration write permission for apply mode.
 
+Repositories can make that policy declarative in `buildchain.toml`:
+
+```toml
+[governance.dev.merge_queue]
+mode = "enabled" # enabled, inherit, or disabled
+required_workflows = [".github/workflows/verify.yml"]
+check_response_timeout_minutes = 120
+max_entries_to_build = 1
+bypass_users = ["release-owner"]
+```
+
+Use `buildchain dev merge-queue --from-config` to resolve and reconcile the
+declaration. `enabled` requires an exact queue on the target dev branch;
+`disabled` suppresses automatic queue creation; `inherit` copies the active
+default dev branch's queue parameters and bypass actors. When the table is
+absent, release-line bootstrap uses the backward-compatible `inherit` mode.
+Every inherited or explicitly enabled queue still validates each declared
+required workflow before any mutation. For a legacy repository with no table,
+an already-active exact queue on the current default dev branch is accepted as
+the inheritance evidence; new declarations should list the workflows so future
+changes are revalidated from source.
+The `Dev Merge Queue Governance` workflow runs this reconciliation after
+governance-relevant changes land on a dev branch; its manual dispatch remains
+dry-run by default.
+
 `buildchain release line open` plans or writes the first version-state commit
 for a new semver minor line. It does not publish anything. The dry-run mode is
 the default and returns the dev/alpha/release refs, protection contract, default
@@ -224,8 +249,9 @@ buildchain release line open \
 The write mode only updates local version-state files. The repository workflow
 `Release Line Bootstrap` wraps this command and, when `apply=true`, commits the
 initial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and
-`release/vX/vX.Y`, applies one-review branch protection, switches the default
-branch, and opens the first dev-to-alpha channel PR:
+`release/vX/vX.Y`, applies one-review branch protection, reconciles declared or
+inherited merge-queue governance, switches the default branch only after that
+reconciliation succeeds, and opens the first dev-to-alpha channel PR:
 
 ```bash
 buildchain release line open \

package/docs/release-flow.md

@@ -108,12 +108,17 @@ When the workflow is run with `apply=true`, Buildchain:
 - applies branch protection with one approving review and the configured
   required status check; dev starts strict, while alpha and release also require
   the pair-specific `verify` aggregate without a source-up-to-date ancestry loop;
+- reconciles the new dev branch's explicitly declared merge queue, or inherits
+  the exact queue parameters and bypass actors from the current default dev
+  branch when the policy is `inherit` or absent;
 - switches the repository default branch to the new dev line when requested;
 - opens the first `dev/v2/v2.10 -> alpha/v2/v2.10` channel PR when requested.
 
 This makes minor-line creation a single audited operation. The channel PR still
 goes through the normal verify/review/promotion path before an alpha is
-published.
+published. Queue reconciliation runs after branch protection and before the
+default-branch switch, so a failed governance apply leaves the old active line
+in place and the idempotently created new refs can be retried.
 
 ## Alpha Promotion
 

package/docs/release-governance.md

@@ -424,6 +424,22 @@ protection. The ruleset uses the first merge method that the repository itself
 allows, and fails closed when the repository has no enabled merge method.
 Re-running the command is idempotent.
 
+The repository policy can be declared once instead of repeated as CLI flags:
+
+```toml
+[governance.dev.merge_queue]
+mode = "inherit"
+required_workflows = [".github/workflows/verify.yml"]
+```
+
+`enabled` explicitly requires Buildchain to create or update an exact-branch
+queue; `inherit` copies queue parameters and bypass actors from the repository's
+current default dev branch; `disabled` prevents automatic queue creation. An
+absent declaration behaves as `inherit` during release-line bootstrap so a new
+major or minor line does not silently lose governance already active on the
+previous line. Required status-check identities still come from the new
+branch's own classic protection rather than being copied from the old branch.
+
 Merge-queue rules also reject generated post-publish version-state ref updates.
 When the sealed promotion workflow uses a dedicated GitHub App, user, or team
 already declared by release governance, repeat `--bypass-app`, `--bypass-user`,

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-17 | extend-minor | `v2.14` | merge-queue-config, release-line-governance-inheritance | additive | Buildchain config can explicitly enable, inherit, or disable exact dev-channel merge queues, and release-line bootstrap reconciles the declared or inherited policy before moving the repository default branch. | |
 | 2026-07-16 | open-minor | `v2.14` | dev-merge-queue-governance | additive | The public CLI adds a dry-run-first, idempotent merge-queue governance command that verifies required workflow event compatibility before applying an exact dev-channel ruleset and removing the strict up-to-date race. | |
 | 2026-07-15 | open-minor | `v2.13` | artifact-verification-envelope, package-subpaths | additive | The public envelope seals exact artifact, provenance, identity, lifecycle, revocation, and existing KFD assessment roots into one consumer-ready KFX admission input, with a dedicated Node API export and fail-closed verifier. | |
 | 2026-07-11 | open-minor | `v2.12` | channel-build-router, channel-selection-protocol | additive | The public `build.yml` reusable workflow lets consumers declare one build job while Buildchain selects generic major alpha for development/prerelease intent and stable major for production release intent, with explicit overrides, separate locks, and fail-closed ambiguity handling. | |

package/package.json

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

package/packages/core/buildchain-config.js

@@ -20,6 +20,7 @@ const SUPPORTED_PUBLISH_AUTH = new Set(["trusted-publishing", "npm-token"]);
 const SUPPORTED_PUBLISH_KINDS = new Set(["npm-package", "npm-paper-package"]);
 const SUPPORTED_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
 const SUPPORTED_STABLE_RELEASE_STRATEGIES = new Set(["manual", "latest-qualified-alpha"]);
+const SUPPORTED_MERGE_QUEUE_MODES = new Set(["inherit", "enabled", "disabled"]);
 const SUPPORTED_NATIVE_COMPILER_CACHE = new Set(["auto", "ccache", "sccache", "none"]);
 const WEB_SURFACE_CHANNELS = ["preview", "staging", "production"];
 const SUPPORTED_CHANNEL_VISIBILITY = new Set(["ephemeral", "protected", "public", "internal"]);
@@ -184,6 +185,9 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.release !== undefined) {
     normalized.release = normalizeReleaseSection(normalized.release);
   }
+  if (normalized.governance !== undefined) {
+    normalized.governance = normalizeGovernanceSection(normalized.governance);
+  }
   if (normalized.channels !== undefined) {
     normalized.channels = normalizeChannelsSection(normalized.channels, normalized.project);
   }
@@ -219,6 +223,53 @@ export function normalizeBuildchainConfig(config) {
   return normalized;
 }
 
+function normalizeGovernanceSection(governance) {
+  assertPlainObject(governance, "governance");
+  const normalized = { ...governance };
+  if (governance.dev !== undefined) {
+    assertPlainObject(governance.dev, "governance.dev");
+    normalized.dev = { ...governance.dev };
+    if (governance.dev.merge_queue !== undefined) {
+      const mergeQueue = assertPlainObject(governance.dev.merge_queue, "governance.dev.merge_queue");
+      const mode = mergeQueue.mode === undefined
+        ? "inherit"
+        : assertString(mergeQueue.mode, "governance.dev.merge_queue.mode");
+      if (!SUPPORTED_MERGE_QUEUE_MODES.has(mode)) {
+        throw new Error("governance.dev.merge_queue.mode must be one of inherit, enabled, or disabled");
+      }
+      const checkResponseTimeoutMinutes = mergeQueue.check_response_timeout_minutes === undefined
+        ? 120
+        : Number(mergeQueue.check_response_timeout_minutes);
+      const maxEntriesToBuild = mergeQueue.max_entries_to_build === undefined
+        ? 1
+        : Number(mergeQueue.max_entries_to_build);
+      if (!Number.isInteger(checkResponseTimeoutMinutes) || checkResponseTimeoutMinutes < 1) {
+        throw new Error("governance.dev.merge_queue.check_response_timeout_minutes must be a positive integer");
+      }
+      if (!Number.isInteger(maxEntriesToBuild) || maxEntriesToBuild < 1) {
+        throw new Error("governance.dev.merge_queue.max_entries_to_build must be a positive integer");
+      }
+      normalized.dev = {
+        ...governance.dev,
+        mergeQueue: {
+          mode,
+          requiredWorkflows: normalizeStringArray(
+            mergeQueue.required_workflows,
+            "governance.dev.merge_queue.required_workflows",
+          ),
+          checkResponseTimeoutMinutes,
+          maxEntriesToBuild,
+          bypassApps: normalizeStringArray(mergeQueue.bypass_apps, "governance.dev.merge_queue.bypass_apps"),
+          bypassUsers: normalizeStringArray(mergeQueue.bypass_users, "governance.dev.merge_queue.bypass_users"),
+          bypassTeams: normalizeStringArray(mergeQueue.bypass_teams, "governance.dev.merge_queue.bypass_teams"),
+        },
+      };
+      delete normalized.dev.merge_queue;
+    }
+  }
+  return normalized;
+}
+
 function normalizeReleaseSection(release) {
   assertPlainObject(release, "release");
   const normalized = { ...release };
@@ -1451,6 +1502,7 @@ export function validateBuildchainConfig(
     lifecycleStages,
     publish: loadedConfig.config.publish,
     release: loadedConfig.config.release,
+    governance: loadedConfig.config.governance,
     facts: loadedConfig.config.facts,
     publication: loadedConfig.config.publication,
   };

package/packages/core/buildchain-publication-authority.js

@@ -25,6 +25,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-patrol.yml", "governance-write"],
   [".github/workflows/buildchain-ref-promotion.yml", "governance-write"],
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
   [".github/workflows/npm-publish.yml", "dry-run-only"],
   [".github/workflows/paper-release-sealed.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],

package/packages/core/release-line-bootstrap.js

@@ -158,6 +158,8 @@ export function planReleaseLineBootstrap({
   const alphaRef = `alpha/v${parsedMajor}/${line}`;
   const releaseRef = `release/v${parsedMajor}/${line}`;
   const loadedConfig = loadBuildchainConfig(cwd);
+  const declaredMergeQueue = loadedConfig?.config?.governance?.dev?.mergeQueue;
+  const mergeQueueMode = declaredMergeQueue?.mode || "inherit";
   const versionFiles = discoverVersionStateFiles(cwd, loadedConfig);
   const lifecycleVersionState =
     getLifecycleStage(loadedConfig, "version-state") ||
@@ -201,22 +203,33 @@ export function planReleaseLineBootstrap({
       enforceAdmins: true,
       protectedRefs: [devRef, alphaRef, releaseRef],
     },
+    governance: {
+      mergeQueue: {
+        declared: Boolean(declaredMergeQueue),
+        mode: mergeQueueMode,
+        source: mergeQueueMode === "inherit" ? "repository-default-branch" : "buildchain-config",
+        requiredWorkflows: declaredMergeQueue?.requiredWorkflows || [],
+        reconcileBeforeDefaultBranchSwitch: true,
+      },
+    },
     repositoryActions: [
       { action: "create-or-verify-source-ref", ref: source },
       { action: "commit-initial-version-state", ref: branch, version: resolvedInitialVersion },
       { action: "create-dev-branch", ref: devRef, from: branch },
       { action: "create-alpha-branch", ref: alphaRef, from: source },
       { action: "create-release-branch", ref: releaseRef, from: source },
-      ...(setDefault ? [{ action: "set-default-branch", ref: devRef }] : []),
       { action: "protect-branch", ref: devRef },
       { action: "protect-branch", ref: alphaRef },
       { action: "protect-branch", ref: releaseRef },
+      { action: "reconcile-dev-merge-queue", ref: devRef, mode: mergeQueueMode },
+      ...(setDefault ? [{ action: "set-default-branch", ref: devRef }] : []),
       ...(createAlphaPr ? [{ action: "open-alpha-pr", head: devRef, base: alphaRef }] : []),
     ],
     notes: [
       "This bootstrap creates the new minor line before the first alpha promotion.",
       "The source ref stays as the baseline for alpha/release until reviewed channel PRs move them.",
       "The dev branch receives only the initial version-state commit and becomes the active line when setDefault is true.",
+      "Merge queue governance is reconciled after branch protection and before the repository default branch moves.",
     ],
   };
 }