@kungfu-tech/buildchain 2.4.11 → 2.5.0-alpha.0

package/CONTRIBUTING.md

@@ -103,6 +103,15 @@ release/vX/vX.Y -> publish-gate/major
 ```
 
 - Open normal changes against the relevant `dev/*` branch.
+- Treat `dev/vX/vX.Y` branches as protected development channels. Do not use
+  them for direct ad-hoc commits. Work from `feature/*`, `fix/*`, `chore/*`,
+  `docs/*`, `ci/*`, or `refactor/*` branches and open a PR into the target dev
+  line.
+- Repositories may call
+  `.github/workflows/dev-pr-auto-merge.yml` from their own scheduled or manual
+  wrapper to merge ready, conflict-free dev PRs. The wrapper is policy-gated:
+  required checks, ready/block labels, same-repository heads, approvals,
+  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

package/dist/site/buildchain-site.json

@@ -141,6 +141,9 @@
       "release/vX/vX.Y",
       "publish-gate/major"
     ],
+    "protectedDevelopmentBranches": [
+      "dev/vX/vX.Y"
+    ],
     "releasePassport": {
       "entrypoint": "buildchain.release.json",
       "bundle": "buildchain-release-bundle.tar.gz",

package/dist/site/release-model.json

@@ -9,6 +9,9 @@
     "release/vX/vX.Y",
     "publish-gate/major"
   ],
+  "protectedDevelopmentBranches": [
+    "dev/vX/vX.Y"
+  ],
   "releasePassport": {
     "entrypoint": "buildchain.release.json",
     "bundle": "buildchain-release-bundle.tar.gz",

package/dist/site/workflow-registry.json

@@ -20,6 +20,12 @@
       "surface": "release-governance",
       "status": "active"
     },
+    {
+      "id": "dev-pr-auto-merge",
+      "path": ".github/workflows/dev-pr-auto-merge.yml",
+      "surface": "dev-governance",
+      "status": "active"
+    },
     {
       "id": "binary-distribution",
       "path": ".github/workflows/binary-distribution.yml",

package/docs/MAP.md

@@ -24,6 +24,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |
 | How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
+| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |
 | How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
 | What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |
 | What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |
@@ -57,6 +58,8 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`versioning.md`](versioning.md).
 - **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)
   and [`release-flow.md`](release-flow.md).
+- **protected dev branches / scheduled ready-PR merge** ->
+  [`release-governance.md`](release-governance.md#protected-dev-branches).
 - **pnpm / npm / yarn / package-manager adapters** ->
   [`lifecycle-protocol.md`](lifecycle-protocol.md).
 - **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)

package/docs/migration-inventory.md

@@ -21,13 +21,14 @@ The active Buildchain-native reusable surface is:
 | --- | --- |
 | `.github/workflows/.build.yml` | active reusable build contract: runner presets, trusted event gate, publish source lock, lifecycle commands, deterministic artifacts, aggregate summary, and release manifest outputs |
 
-Other hidden reusable workflow files from the old `workflows` repository may
-still exist in `.github/workflows`. They are retained so the repository can lint
-them, document migration boundaries, and make retired paths fail closed. They
-are not new Buildchain v2 integration targets unless a dedicated document says
-otherwise. In particular, the legacy `.release-new-version.yml` path is not the
-modern publish surface; new publish integrations should use `.build.yml`,
-`buildchain.toml`, `lifecycle.publish`, and publish transaction evidence.
+Hidden reusable workflow files from the old `workflows` repository are retained
+only when they still have an active compatibility or migration boundary. Retired
+PR orchestration paths are not kept in `.github/workflows`; they remain listed
+in the inventory as excluded legacy surfaces. In particular,
+`.batch-pull-request.yml` is removed with the retired batch PR action family,
+and the legacy `.release-new-version.yml` path is not the modern publish
+surface. New publish integrations should use `.build.yml`, `buildchain.toml`,
+`lifecycle.publish`, and publish transaction evidence.
 
 ## Migrated Actions
 
@@ -64,6 +65,15 @@ because the action is part of that retired path.
 | `action-sync-pr` | retired PR synchronization helper; not part of the Buildchain reusable contract |
 | `action-update-dependencies-version` | retired dependency-version helper; use package-manager adapters and lifecycle commands |
 
+## Retired Workflows Excluded From v2
+
+These legacy workflow entrypoints are intentionally not shipped from the root
+`.github/workflows` directory.
+
+| Previous workflow | Reason |
+| --- | --- |
+| `.batch-pull-request.yml` | retired PR orchestration helper; v2.5 dev integration governance will use a new protected-dev PR protocol instead |
+
 ## Buildchain-Native Actions
 
 These actions are new Buildchain v2 surfaces rather than migrations from an

package/docs/release-governance.md

@@ -219,6 +219,68 @@ Checking out `publish-gate/major` should therefore look like a frozen release
 state, not like a branch where day-to-day source work continues. Day-to-day
 source work continues on `dev/vX/vX.Y`.
 
+## Protected Dev Branches
+
+`dev/vX/vX.Y` is a protected development channel, not a scratch branch. Normal
+source changes should be made on work branches such as `feature/*`, `fix/*`,
+`chore/*`, `docs/*`, `ci/*`, or `refactor/*`, then reviewed through a pull
+request into the target dev line.
+
+This keeps the earliest development channel audit-friendly:
+
+- the version line being changed is visible in the PR base branch;
+- CI and required checks run before the channel moves;
+- branch protection can prevent direct pushes and stale merges;
+- later `dev -> alpha -> release` promotion inherits a reviewable source
+  lineage instead of trying to reconstruct how the dev branch changed.
+
+Buildchain provides the reusable
+`.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a
+scheduled or manual "merge ready dev PRs" pass. The consumer repository owns
+the trigger schedule, but the merge decision is declared through workflow
+inputs: target dev branch, required status/check names, ready and block labels,
+allowed work-branch prefixes, review requirements, maximum merges per run,
+merge method, and dry-run mode.
+
+The workflow defaults are conservative. A PR is skipped unless it targets the
+configured dev line, is not a draft, has the ready label, has no block label,
+comes from the same repository, uses an allowed work-branch prefix, has a
+current approval, is mergeable, and has the configured required checks passing.
+After each merge, the next PR is re-evaluated before it can move the protected
+dev branch. This prevents one merge from silently making the next candidate
+stale or conflicting.
+
+Typical consumer wrapper:
+
+```yaml
+name: Merge Ready Dev PRs
+
+on:
+  schedule:
+    - cron: "17 * * * *"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        type: boolean
+        default: true
+
+jobs:
+  merge-dev:
+    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v2
+    permissions:
+      contents: write
+      pull-requests: write
+      checks: read
+      statuses: read
+    with:
+      target-branch: dev/v2/v2.5
+      required-status-checks: Verify
+      ready-label: ready
+      block-labels: blocked,do-not-merge
+      max-merges: 1
+      dry-run: ${{ inputs.dry-run || false }}
+```
+
 ## Package-Manager Adapters
 
 Old ABV assumed JavaScript repositories with root version state and often

package/docs/versioning.md

@@ -44,6 +44,7 @@ expected ref flow requires a major bump.
 | 2026-07-02 | Release passport and binary distribution are a minor surface. | `v2.2` | They add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. |
 | 2026-07-02 | Web surface host mapping is a minor surface. | `v2.3` | It adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. |
 | 2026-07-03 | Infra contract lifecycle is a minor surface. | `v2.4` | It adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. |
+| 2026-07-04 | Scheduled integration governance is a minor surface. | `v2.5` | It adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. |
 
 ## Runner Policy
 

package/package.json

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

package/scripts/check-inventory.mjs

@@ -41,6 +41,7 @@ const requiredPaths = [
   ".github/actionlint.yaml",
   ".github/workflows/self-hosted-runner-smoke.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
+  ".github/workflows/dev-pr-auto-merge.yml",
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/npm-publish.yml",
   ".github/workflows/binary-distribution.yml",
@@ -329,6 +330,9 @@ if (!Array.isArray(inventory.workflowSources) || inventory.workflowSources.lengt
 if (!Array.isArray(inventory.retiredActionsExcluded) || inventory.retiredActionsExcluded.length === 0) {
   throw new Error("retiredActionsExcluded must list retired legacy actions");
 }
+if (!Array.isArray(inventory.retiredWorkflowsExcluded) || inventory.retiredWorkflowsExcluded.length === 0) {
+  throw new Error("retiredWorkflowsExcluded must list retired legacy workflows");
+}
 
 const actualActions = fs
   .readdirSync(path.join(root, "actions"), { withFileTypes: true })
@@ -356,6 +360,13 @@ for (const retiredRepo of inventory.retiredActionsExcluded || []) {
   }
 }
 
+for (const retiredWorkflow of inventory.retiredWorkflowsExcluded || []) {
+  const retiredPath = path.join(root, retiredWorkflow);
+  if (fs.existsSync(retiredPath)) {
+    throw new Error(`retired workflow must not be shipped in buildchain v2: ${retiredWorkflow}`);
+  }
+}
+
 for (const action of shippedActions) {
   for (const key of ["path", "runtime", "build", "bundle"]) {
     if (!action[key]) {

package/scripts/dev-pr-auto-merge.mjs

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_BLOCK_LABELS = ["blocked", "do-not-merge", "work-in-progress"];
+const DEFAULT_ALLOWED_HEAD_PREFIXES = ["feature/", "fix/", "chore/", "docs/", "ci/", "refactor/"];
+const DEFAULT_REQUIRED_CHECKS = ["Verify"];
+const SUCCESS_STATES = new Set(["success"]);
+const SUCCESS_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);
+
+function splitList(value, fallback = []) {
+  if (Array.isArray(value)) return value.map((entry) => String(entry).trim()).filter(Boolean);
+  const text = String(value ?? "").trim();
+  if (!text) return [...fallback];
+  return text
+    .split(/[\n,]+/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function boolOption(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  const text = String(value).trim().toLowerCase();
+  return ["1", "true", "yes", "on"].includes(text);
+}
+
+function intOption(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : fallback;
+}
+
+function normalizeRepo(value) {
+  const text = String(value || "").trim();
+  const match = text.match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) throw new Error(`repository must be owner/repo, got: ${text || "<empty>"}`);
+  return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    repository: normalizeRepo(options.repository || process.env.GITHUB_REPOSITORY),
+    targetBranch: String(options.targetBranch || "").replace(/^refs\/heads\//, ""),
+    readyLabel: String(options.readyLabel ?? "ready").trim(),
+    blockLabels: splitList(options.blockLabels, DEFAULT_BLOCK_LABELS).map((label) => label.toLowerCase()),
+    allowedHeadPrefixes: splitList(options.allowedHeadPrefixes, DEFAULT_ALLOWED_HEAD_PREFIXES),
+    requiredChecks: splitList(options.requiredChecks, DEFAULT_REQUIRED_CHECKS),
+    requireApproval: boolOption(options.requireApproval, true),
+    sameRepositoryOnly: boolOption(options.sameRepositoryOnly, true),
+    maxMerges: intOption(options.maxMerges, 1),
+    mergeMethod: String(options.mergeMethod || "merge").trim(),
+    dryRun: boolOption(options.dryRun, true),
+    pollMergeableAttempts: intOption(options.pollMergeableAttempts, 3),
+    pollMergeableDelayMs: intOption(options.pollMergeableDelayMs, 1000),
+    outputPath: String(options.outputPath || ".buildchain/dev-pr-auto-merge/result.json"),
+  };
+}
+
+function labelsOf(pr) {
+  return (pr.labels || []).map((label) => String(label.name || label).toLowerCase());
+}
+
+function hasReadyLabel(pr, readyLabel) {
+  if (!readyLabel) return true;
+  return labelsOf(pr).includes(readyLabel.toLowerCase());
+}
+
+function hasBlockedLabel(pr, blockLabels) {
+  const labels = labelsOf(pr);
+  return blockLabels.some((label) => labels.includes(label));
+}
+
+function headPrefixAllowed(pr, prefixes) {
+  if (prefixes.length === 0) return true;
+  const headRef = String(pr.head?.ref || "");
+  return prefixes.some((prefix) => headRef.startsWith(prefix));
+}
+
+function sameRepositoryAllowed(pr, repository, sameRepositoryOnly) {
+  if (!sameRepositoryOnly) return true;
+  return pr.head?.repo?.full_name === repository.fullName;
+}
+
+function latestReviewStates(reviews = []) {
+  const latest = new Map();
+  for (const review of reviews) {
+    const user = review.user?.login;
+    if (!user) continue;
+    latest.set(user, String(review.state || "").toUpperCase());
+  }
+  return [...latest.values()];
+}
+
+function hasRequiredApproval(reviews = []) {
+  const states = latestReviewStates(reviews);
+  return states.includes("APPROVED") && !states.includes("CHANGES_REQUESTED");
+}
+
+function checkMatchesRequired(name, required) {
+  const haystack = String(name || "").toLowerCase();
+  return haystack === required.toLowerCase() || haystack.includes(required.toLowerCase());
+}
+
+function summarizeChecks({ statuses = [], checkRuns = [] } = {}, requiredChecks = []) {
+  const summary = [];
+  for (const required of requiredChecks) {
+    const matchingStatuses = statuses.filter((status) => checkMatchesRequired(status.context, required));
+    const matchingRuns = checkRuns.filter((run) => checkMatchesRequired(run.name, required));
+    const passedStatuses = matchingStatuses.filter((status) => SUCCESS_STATES.has(String(status.state || "").toLowerCase()));
+    const passedRuns = matchingRuns.filter((run) => SUCCESS_CONCLUSIONS.has(String(run.conclusion || "").toLowerCase()));
+    const passed = passedStatuses.length > 0 || passedRuns.length > 0;
+    summary.push({
+      required,
+      passed,
+      matches: [
+        ...matchingStatuses.map((status) => ({
+          type: "status",
+          name: status.context,
+          state: status.state,
+        })),
+        ...matchingRuns.map((run) => ({
+          type: "check-run",
+          name: run.name,
+          conclusion: run.conclusion,
+          status: run.status,
+        })),
+      ],
+    });
+  }
+  return {
+    required: requiredChecks,
+    entries: summary,
+    passed: summary.every((entry) => entry.passed),
+  };
+}
+
+function mergeableAccepted(pr) {
+  if (pr.mergeable === false) return false;
+  const state = String(pr.mergeable_state || pr.mergeStateStatus || "").toLowerCase();
+  if (!state) return pr.mergeable === true;
+  return ["clean", "has_hooks", "unstable", "unknown"].includes(state);
+}
+
+function skip(reason, details = {}) {
+  return { action: "skip", reason, ...details };
+}
+
+export async function evaluatePullRequest(pr, options, client) {
+  options = options.repository?.fullName ? options : normalizeOptions(options);
+  if (pr.draft) return skip("draft");
+  if (!sameRepositoryAllowed(pr, options.repository, options.sameRepositoryOnly)) {
+    return skip("fork-or-cross-repository-head", { headRepository: pr.head?.repo?.full_name || "" });
+  }
+  if (!headPrefixAllowed(pr, options.allowedHeadPrefixes)) {
+    return skip("head-prefix-not-allowed", { headRef: pr.head?.ref || "" });
+  }
+  if (!hasReadyLabel(pr, options.readyLabel)) {
+    return skip("missing-ready-label", { requiredLabel: options.readyLabel });
+  }
+  if (hasBlockedLabel(pr, options.blockLabels)) {
+    return skip("blocked-label", { labels: labelsOf(pr) });
+  }
+
+  const detailed = await client.getPullRequest(pr.number, {
+    attempts: options.pollMergeableAttempts,
+    delayMs: options.pollMergeableDelayMs,
+  });
+  if (!mergeableAccepted(detailed)) {
+    return skip("not-mergeable", {
+      mergeable: detailed.mergeable,
+      mergeableState: detailed.mergeable_state || detailed.mergeStateStatus || "",
+    });
+  }
+
+  if (options.requireApproval) {
+    const reviews = await client.listReviews(pr.number);
+    if (!hasRequiredApproval(reviews)) return skip("missing-approval");
+  }
+
+  const checks = await client.listCommitChecks(pr.head?.sha);
+  const checkSummary = summarizeChecks(checks, options.requiredChecks);
+  if (!checkSummary.passed) return skip("required-checks-not-passing", { checks: checkSummary });
+
+  return {
+    action: options.dryRun ? "would-merge" : "merge",
+    reason: options.dryRun ? "dry-run" : "eligible",
+    checks: checkSummary,
+  };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseLinkHeader(header) {
+  const links = {};
+  for (const part of String(header || "").split(",")) {
+    const match = part.match(/<([^>]+)>;\s*rel="([^"]+)"/);
+    if (match) links[match[2]] = match[1];
+  }
+  return links;
+}
+
+export class GitHubClient {
+  constructor({ token, repository, apiUrl = "https://api.github.com", fetchImpl = globalThis.fetch } = {}) {
+    if (!fetchImpl) throw new Error("fetch is required");
+    if (!token) throw new Error("GITHUB_TOKEN is required");
+    this.token = token;
+    this.repository = repository;
+    this.apiUrl = apiUrl.replace(/\/+$/, "");
+    this.fetch = fetchImpl;
+  }
+
+  async request(method, requestPath, { body, accept = "application/vnd.github+json" } = {}) {
+    const url = requestPath.startsWith("http") ? requestPath : `${this.apiUrl}${requestPath}`;
+    const response = await this.fetch(url, {
+      method,
+      headers: {
+        accept,
+        authorization: `Bearer ${this.token}`,
+        "content-type": "application/json",
+        "x-github-api-version": "2022-11-28",
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    const data = text ? JSON.parse(text) : null;
+    if (!response.ok) {
+      const message = data?.message || text || `${method} ${url} failed`;
+      const error = new Error(message);
+      error.status = response.status;
+      error.data = data;
+      throw error;
+    }
+    return { data, response };
+  }
+
+  async paginate(requestPath) {
+    let next = requestPath;
+    const items = [];
+    while (next) {
+      const { data, response } = await this.request("GET", next);
+      items.push(...data);
+      next = parseLinkHeader(response.headers.get("link")).next;
+    }
+    return items;
+  }
+
+  async listPullRequests(base) {
+    const query = new URLSearchParams({
+      state: "open",
+      base,
+      sort: "updated",
+      direction: "asc",
+      per_page: "100",
+    });
+    return this.paginate(`/repos/${this.repository.owner}/${this.repository.repo}/pulls?${query}`);
+  }
+
+  async getPullRequest(number, { attempts = 3, delayMs = 1000 } = {}) {
+    let last;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      const { data } = await this.request(
+        "GET",
+        `/repos/${this.repository.owner}/${this.repository.repo}/pulls/${number}`,
+      );
+      last = data;
+      if (data.mergeable !== null && data.mergeable !== undefined) return data;
+      if (attempt < attempts) await delay(delayMs);
+    }
+    return last;
+  }
+
+  async listReviews(number) {
+    return this.paginate(`/repos/${this.repository.owner}/${this.repository.repo}/pulls/${number}/reviews?per_page=100`);
+  }
+
+  async listCommitChecks(sha) {
+    if (!sha) return { statuses: [], checkRuns: [] };
+    const [{ data: statusData }, { data: checkRunData }] = await Promise.all([
+      this.request("GET", `/repos/${this.repository.owner}/${this.repository.repo}/commits/${sha}/status`),
+      this.request("GET", `/repos/${this.repository.owner}/${this.repository.repo}/commits/${sha}/check-runs?per_page=100`),
+    ]);
+    return {
+      statuses: statusData.statuses || [],
+      checkRuns: checkRunData.check_runs || [],
+    };
+  }
+
+  async mergePullRequest(number, { method, sha }) {
+    const { data } = await this.request("PUT", `/repos/${this.repository.owner}/${this.repository.repo}/pulls/${number}/merge`, {
+      body: {
+        merge_method: method,
+        sha,
+      },
+    });
+    return data;
+  }
+
+  async getBranchSha(branch) {
+    const ref = encodeURIComponent(`heads/${branch}`).replace(/%2F/g, "/");
+    const { data } = await this.request("GET", `/repos/${this.repository.owner}/${this.repository.repo}/git/ref/${ref}`);
+    return data.object?.sha || "";
+  }
+}
+
+export async function runDevPrAutoMerge(optionsInput = {}, clientInput) {
+  const options = normalizeOptions(optionsInput);
+  if (!options.targetBranch) throw new Error("target branch is required");
+  const client = clientInput || new GitHubClient({
+    token: optionsInput.token || process.env.GITHUB_TOKEN,
+    repository: options.repository,
+    apiUrl: optionsInput.apiUrl || process.env.GITHUB_API_URL || "https://api.github.com",
+  });
+
+  const pullRequests = await client.listPullRequests(options.targetBranch);
+  const result = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-dev-pr-auto-merge",
+    repository: options.repository.fullName,
+    targetBranch: options.targetBranch,
+    dryRun: options.dryRun,
+    maxMerges: options.maxMerges,
+    evaluated: [],
+    merged: [],
+    skipped: [],
+    finalBaseSha: "",
+  };
+
+  for (const pr of pullRequests) {
+    if (result.merged.length >= options.maxMerges) {
+      const entry = { number: pr.number, title: pr.title || "", action: "skip", reason: "max-merges-reached" };
+      result.evaluated.push(entry);
+      result.skipped.push(entry);
+      continue;
+    }
+
+    const decision = await evaluatePullRequest(pr, options, client);
+    const entry = {
+      number: pr.number,
+      title: pr.title || "",
+      headRef: pr.head?.ref || "",
+      headSha: pr.head?.sha || "",
+      action: decision.action,
+      reason: decision.reason,
+      checks: decision.checks,
+    };
+    result.evaluated.push(entry);
+
+    if (decision.action === "merge") {
+      const mergeResult = await client.mergePullRequest(pr.number, {
+        method: options.mergeMethod,
+        sha: pr.head?.sha,
+      });
+      const mergedEntry = { ...entry, mergeSha: mergeResult.sha || "" };
+      result.merged.push(mergedEntry);
+      result.evaluated[result.evaluated.length - 1] = mergedEntry;
+    } else if (decision.action === "would-merge") {
+      result.merged.push(entry);
+    } else {
+      result.skipped.push(entry);
+    }
+  }
+
+  result.finalBaseSha = await client.getBranchSha(options.targetBranch).catch(() => "");
+  return result;
+}
+
+export function renderMarkdownSummary(result) {
+  const lines = [
+    "## Buildchain dev PR auto-merge",
+    "",
+    `Repository: \`${result.repository}\``,
+    `Target branch: \`${result.targetBranch}\``,
+    `Mode: \`${result.dryRun ? "dry-run" : "merge"}\``,
+    `Evaluated PRs: ${result.evaluated.length}`,
+    `Eligible ${result.dryRun ? "dry-run" : "merged"} PRs: ${result.merged.length}`,
+    "",
+    "| PR | Action | Reason | Head |",
+    "| --- | --- | --- | --- |",
+  ];
+  for (const entry of result.evaluated) {
+    lines.push(`| #${entry.number} | ${entry.action} | ${entry.reason} | \`${entry.headRef || ""}\` |`);
+  }
+  if (result.evaluated.length === 0) lines.push("| - | skip | no open pull requests | - |");
+  if (!result.dryRun && result.finalBaseSha) {
+    lines.push("", `Final target branch SHA: \`${result.finalBaseSha}\``);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function writeGitHubOutputs(outputs, outputFile = process.env.GITHUB_OUTPUT) {
+  if (!outputFile) return;
+  const lines = [];
+  for (const [key, value] of Object.entries(outputs)) {
+    lines.push(`${key}=${String(value).replace(/\n/g, "%0A")}`);
+  }
+  fs.appendFileSync(outputFile, `${lines.join("\n")}\n`);
+}
+
+async function main() {
+  const options = normalizeOptions({
+    repository: process.env.BUILDCHAIN_DEV_PR_REPOSITORY || process.env.GITHUB_REPOSITORY,
+    targetBranch: process.env.BUILDCHAIN_DEV_PR_TARGET_BRANCH || process.env.GITHUB_REF_NAME,
+    readyLabel: process.env.BUILDCHAIN_DEV_PR_READY_LABEL,
+    blockLabels: process.env.BUILDCHAIN_DEV_PR_BLOCK_LABELS,
+    allowedHeadPrefixes: process.env.BUILDCHAIN_DEV_PR_ALLOWED_HEAD_PREFIXES,
+    requiredChecks: process.env.BUILDCHAIN_DEV_PR_REQUIRED_CHECKS,
+    requireApproval: process.env.BUILDCHAIN_DEV_PR_REQUIRE_APPROVAL,
+    sameRepositoryOnly: process.env.BUILDCHAIN_DEV_PR_SAME_REPOSITORY_ONLY,
+    maxMerges: process.env.BUILDCHAIN_DEV_PR_MAX_MERGES,
+    mergeMethod: process.env.BUILDCHAIN_DEV_PR_MERGE_METHOD,
+    dryRun: process.env.BUILDCHAIN_DEV_PR_DRY_RUN,
+    outputPath: process.env.BUILDCHAIN_DEV_PR_OUTPUT_PATH,
+  });
+  const result = await runDevPrAutoMerge(options);
+  fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
+  fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`);
+  const summary = renderMarkdownSummary(result);
+  if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+  else process.stdout.write(summary);
+  writeGitHubOutputs({
+    "evaluated-count": result.evaluated.length,
+    "merged-count": result.merged.length,
+    "skipped-count": result.skipped.length,
+    "final-base-sha": result.finalBaseSha,
+    "result-path": options.outputPath,
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/scripts/generate-site-bundle.mjs

@@ -84,6 +84,7 @@ function buildSiteBundle() {
       { id: "build", path: ".github/workflows/.build.yml", surface: "reusable-build", status: "active" },
       { id: "web-surface", path: ".github/workflows/.web-surface.yml", surface: "site-app-deployment", status: "active" },
       { id: "buildchain-ref-promotion", path: ".github/workflows/buildchain-ref-promotion.yml", surface: "release-governance", status: "active" },
+      { id: "dev-pr-auto-merge", path: ".github/workflows/dev-pr-auto-merge.yml", surface: "dev-governance", status: "active" },
       { id: "binary-distribution", path: ".github/workflows/binary-distribution.yml", surface: "release-passport", status: "active" },
     ],
     actions: [
@@ -99,6 +100,7 @@ function buildSiteBundle() {
     exactTags: "v-prefixed exact tags are immutable release records.",
     floatingTags: "vX, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions.",
     channelBranches: ["dev/vX/vX.Y", "alpha/vX/vX.Y", "release/vX/vX.Y", "publish-gate/major"],
+    protectedDevelopmentBranches: ["dev/vX/vX.Y"],
     releasePassport: {
       entrypoint: "buildchain.release.json",
       bundle: "buildchain-release-bundle.tar.gz",

package/scripts/workflow-friction-report.mjs

@@ -4,7 +4,17 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
-const DEFAULT_BUILD_WORKFLOW_FILE = "build-surface-fixture.yml";
+const DEFAULT_BUILD_WORKFLOW_FILE = "build.yml";
+const DEFAULT_BUILD_WORKFLOW_NAME = "Build";
+
+class GitHubApiError extends Error {
+  constructor(message, { status, path: requestPath } = {}) {
+    super(message);
+    this.name = "GitHubApiError";
+    this.status = status;
+    this.path = requestPath;
+  }
+}
 
 function env(name, fallback = "") {
   return process.env[name] || fallback;
@@ -48,11 +58,71 @@ async function githubJson({ apiUrl, token, path: requestPath, fetchImpl = global
   const text = await response.text();
   const body = text ? JSON.parse(text) : {};
   if (!response.ok) {
-    throw new Error(`GitHub API ${requestPath} failed with ${response.status}: ${body.message || text}`);
+    throw new GitHubApiError(`GitHub API ${requestPath} failed with ${response.status}: ${body.message || text}`, {
+      status: response.status,
+      path: requestPath,
+    });
   }
   return body;
 }
 
+function workflowRunMatchesConfiguredWorkflow(run, { buildWorkflowFile = "", buildWorkflowName = "" } = {}) {
+  const expectedName = String(buildWorkflowName || "").trim();
+  const expectedFile = String(buildWorkflowFile || "").trim();
+  const runName = String(run.name || run.workflow_name || "").trim();
+  const runPath = String(run.path || run.workflow_path || "").trim();
+  if (expectedName && runName === expectedName) {
+    return true;
+  }
+  if (expectedFile && (runPath === expectedFile || runPath.endsWith(`/${expectedFile}`))) {
+    return true;
+  }
+  return !expectedName && !expectedFile;
+}
+
+async function listPullRequestWorkflowRuns({
+  apiUrl,
+  token,
+  repo,
+  buildWorkflowFile,
+  buildWorkflowName,
+  fetchImpl,
+}) {
+  const diagnostics = [];
+  const workflowFile = String(buildWorkflowFile || "").trim();
+  if (workflowFile) {
+    try {
+      const runs = await githubJson({
+        apiUrl,
+        token,
+        fetchImpl,
+        path: `/repos/${repo.owner}/${repo.repo}/actions/workflows/${encodeURIComponent(workflowFile)}/runs?event=pull_request&per_page=100`,
+      });
+      return {
+        runs: Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [],
+        diagnostics,
+      };
+    } catch (error) {
+      if (error.status !== 404) {
+        throw error;
+      }
+      diagnostics.push(`Configured PR-stage workflow file ${workflowFile} was not found; fell back to repository pull_request workflow runs.`);
+    }
+  }
+
+  const runs = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repo.owner}/${repo.repo}/actions/runs?event=pull_request&per_page=100`,
+  });
+  return {
+    runs: (Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [])
+      .filter((run) => workflowRunMatchesConfiguredWorkflow(run, { buildWorkflowFile, buildWorkflowName })),
+    diagnostics,
+  };
+}
+
 function runLabel(run = "") {
   if (typeof run === "string") {
     return run;
@@ -129,6 +199,7 @@ export async function classifyWorkflowFriction({
   token = env("GITHUB_TOKEN"),
   apiUrl = env("GITHUB_API_URL", "https://api.github.com"),
   buildWorkflowFile = DEFAULT_BUILD_WORKFLOW_FILE,
+  buildWorkflowName = DEFAULT_BUILD_WORKFLOW_NAME,
   releaseCandidateOutcome = env("BUILDCHAIN_RC_RESOLVE_OUTCOME"),
   releaseCandidateDiagnosis = env("BUILDCHAIN_RC_DIAGNOSIS"),
   runUrl = env("BUILDCHAIN_WORKFLOW_RUN_URL"),
@@ -154,14 +225,18 @@ export async function classifyWorkflowFriction({
 
   let relatedRuns = [];
   let heavyBuilds = [];
+  let workflowRunDiagnostics = [];
   if (primaryPullRequest?.number) {
-    const runs = await githubJson({
+    const workflowRuns = await listPullRequestWorkflowRuns({
       apiUrl,
       token,
+      repo,
+      buildWorkflowFile,
+      buildWorkflowName,
       fetchImpl,
-      path: `/repos/${repo.owner}/${repo.repo}/actions/workflows/${encodeURIComponent(buildWorkflowFile)}/runs?event=pull_request&per_page=100`,
     });
-    relatedRuns = (Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [])
+    workflowRunDiagnostics = workflowRuns.diagnostics;
+    relatedRuns = workflowRuns.runs
       .filter((run) => (run.pull_requests || []).some((pr) => Number(pr.number || 0) === Number(primaryPullRequest.number)));
     heavyBuilds = relatedRuns.filter((run) => run.status === "completed" && ["success", "failure", "cancelled", "timed_out"].includes(run.conclusion || ""));
   }
@@ -184,6 +259,7 @@ export async function classifyWorkflowFriction({
   if (releaseCandidateDiagnosis) {
     diagnosisParts.push(releaseCandidateDiagnosis);
   }
+  diagnosisParts.push(...workflowRunDiagnostics);
   const diagnosis = diagnosisParts.join(" ") || "Buildchain ref promotion failed after Verify succeeded; inspect the classified evidence and keep the fix in Buildchain.";
   const nextAction = frictionClass === "late-fail-fast"
     ? "Move the missing/stale RC evidence check earlier or make the promotion workflow consume the exact PR-stage RC passport before any publish side effect."
@@ -229,6 +305,7 @@ export async function workflowFrictionReportCli() {
       targetRef: env("BUILDCHAIN_TARGET_REF"),
       targetSha: env("BUILDCHAIN_TARGET_SHA"),
       buildWorkflowFile: env("BUILDCHAIN_BUILD_WORKFLOW_FILE", DEFAULT_BUILD_WORKFLOW_FILE),
+      buildWorkflowName: env("BUILDCHAIN_BUILD_WORKFLOW_NAME", env("BUILDCHAIN_RC_WORKFLOW_NAME", DEFAULT_BUILD_WORKFLOW_NAME)),
       outputDir: env("BUILDCHAIN_FRICTION_OUTPUT_DIR", ".buildchain/workflow-friction"),
     });
   } catch (error) {