@kungfu-tech/buildchain 2.4.6 → 2.4.7-alpha.1

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

@@ -145,11 +145,13 @@ and fail before publish-gate side effects if it no longer matches:
     release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json
 ```
 
-The action validates repository, channel, source SHA, platform matrix, and the
-aggregate build-summary hash before it writes version state, opens release-state,
-runs publish transaction logic, or moves tags/branches. If validation fails, run
-or attach the verified channel PR build first instead of promoting a stale or
-unproven artifact set.
+The action validates repository, channel, source identity, platform matrix, and
+the aggregate build-summary hash before it writes version state, opens
+release-state, runs publish transaction logic, or moves tags/branches. Source
+identity accepts the exact source SHA, the PR merge ref SHA, or the promoted
+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.
 
 When enabled, the action creates or resumes a release transaction keyed by
 repository, version, source SHA, and target ref. It persists that transaction to

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

@@ -40,6 +40,8 @@ By default issue reporting is fail-soft:
   build failure.
 - transient GitHub API 429/5xx errors and connection failures are retried.
 - if a configured label is missing, issue creation is retried without labels.
+- if issue creation/commenting is still unavailable, the action writes the full
+  copyable issue title, fingerprint, and body into the workflow summary.
 - common token, private-key, password, and authorization values are redacted
   before submission.
 
@@ -69,6 +71,8 @@ steps:
       channel: alpha/v2/v2.4
       source-sha: ${{ github.sha }}
       friction-class: duplicate-build
+      related-runs-json: ${{ steps.classify.outputs.related-runs-json }}
+      heavy-builds-json: ${{ steps.classify.outputs.heavy-builds-json }}
       comment-cooldown-hours: "24"
 ```
 

package/docs/release-candidate.md

@@ -34,7 +34,8 @@ contains:
 - repository and pull request context;
 - target channel, target ref, and product version or a non-publish
   `source-<shortSha>` candidate label;
-- source head SHA, merge ref SHA, and source tree hash;
+- source head SHA, merge ref SHA, and the Git `HEAD^{tree}` SHA for PR merge
+  equivalence after the channel PR lands;
 - Buildchain runtime ref/SHA and workflow shell ref;
 - workflow run id/attempt/url;
 - normalized platform matrix and artifact summaries;
@@ -55,8 +56,10 @@ Promotion workflows that should not rebuild artifacts can enable:
 
 With `promote-only-release-candidate: "true"`, promotion fails before
 version-state, publish transaction, tag, or branch side effects when the
-passport does not match the repository, channel, source SHA, platform matrix,
-or build-summary hash. The diagnostic tells maintainers to run or attach the
-verified channel PR build first instead of allowing publish-gate to discover
-the mismatch late.
-
+passport does not match the repository, channel, source identity, platform
+matrix, or build-summary hash. Source identity accepts the exact PR source SHA,
+the PR merge ref SHA, or an exact Git tree match with the promoted channel HEAD;
+this keeps post-merge channel commits strict without forcing a rebuild. The
+Buildchain-owned promotion workflow resolves the matching same-repository
+merged channel PR and downloads its PR-stage RC passport automatically before
+promotion starts.

package/docs/reusable-build-surface.md

@@ -242,7 +242,9 @@ the artifact source promoted later. Buildchain then uploads
 `<artifact-name>-release-candidate-<publish-source-sha>` artifact name. Promotion
 jobs can pass that passport to `promote-buildchain-ref` with
 `promote-only-release-candidate: "true"` so source, channel, platforms, and the
-aggregate build-summary hash are checked before publish-gate side effects.
+aggregate build-summary hash are checked before publish-gate side effects. The
+passport records the locked commit's Git tree SHA, so a post-merge channel HEAD
+can be accepted only when it is tree-equivalent to the PR-stage build evidence.
 
 ## Publish Gate
 

package/package.json

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

package/packages/core/issue-reporting.js

@@ -246,6 +246,7 @@ export function buildWorkflowFrictionIssueReport(options = {}) {
         heavyBuilds.length ? `## Heavy build jobs\n\n${heavyBuilds.map((job) => `- ${job.name || job}: ${job.durationMs || ""}`).join("\n")}` : "",
         options.diagnosis ? `## Diagnosis\n\n${options.diagnosis}` : "",
         options.nextAction ? `## Suggested next action\n\n${options.nextAction}` : "",
+        options.body ? `## Details\n\n${options.body}` : "",
       ].filter(Boolean).join("\n"),
     ),
     Number(options.maxBodyBytes || DEFAULT_MAX_BODY_BYTES),

package/packages/core/release-candidate.js

@@ -102,7 +102,7 @@ export function createReleaseCandidatePassport({
       headSha: nonEmptyString(sourceSha, "sourceHeadSha"),
       baseSha: optionalString(baseSha),
       mergeRefSha: optionalString(mergeRefSha || sourceSha),
-      treeHash: optionalString(sourceTreeHash || sha256Json(normalizedSummary.platforms || [])),
+      treeHash: optionalString(sourceTreeHash || normalizedSummary.git?.treeSha),
     },
     buildchain: {
       ref: optionalString(buildchain.ref || normalizedSummary.runtime?.ref),

package/scripts/aggregate-build-summary.mjs

@@ -28,6 +28,7 @@ export function aggregateBuildSummaryCli() {
     git: {
       repository: process.env.GITHUB_REPOSITORY || "",
       sha: process.env.BUILDCHAIN_SOURCE_SHA || process.env.GITHUB_SHA || "",
+      treeSha: process.env.BUILDCHAIN_SOURCE_TREE_SHA || "",
       ref: process.env.BUILDCHAIN_SOURCE_REF || process.env.GITHUB_REF || "",
       runId: process.env.GITHUB_RUN_ID || "",
       runAttempt: process.env.GITHUB_RUN_ATTEMPT || "",

package/scripts/release-candidate-resolver.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+const DEFAULT_WORKFLOW_FILE = "build-surface-fixture.yml";
+
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function splitRepository(repository) {
+  const match = String(repository || "").trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(`repository must be owner/repo, got ${repository || "<empty>"}`);
+  }
+  return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };
+}
+
+function normalizeBranch(value = "") {
+  return String(value || "").replace(/^refs\/heads\//, "").trim();
+}
+
+function assertSha(value, label = "sha") {
+  const sha = String(value || "").trim();
+  if (!/^[0-9a-f]{40}$/i.test(sha)) {
+    throw new Error(`${label} must be a 40-character Git SHA`);
+  }
+  return sha;
+}
+
+function githubHeaders(token) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "buildchain-release-candidate-resolver",
+    "x-github-api-version": "2022-11-28",
+  };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+async function githubJson({ apiUrl, token, method = "GET", path: requestPath, fetchImpl = globalThis.fetch }) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch is required to resolve release candidate artifacts");
+  }
+  const url = `${String(apiUrl || "https://api.github.com").replace(/\/+$/, "")}${requestPath}`;
+  const response = await fetchImpl(url, { method, headers: githubHeaders(token) });
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : {};
+  if (!response.ok) {
+    throw new Error(`GitHub API ${method} ${requestPath} failed with ${response.status}: ${body.message || text}`);
+  }
+  return body;
+}
+
+async function githubDownload({ apiUrl, token, path: requestPath, outputPath, fetchImpl = globalThis.fetch }) {
+  const url = `${String(apiUrl || "https://api.github.com").replace(/\/+$/, "")}${requestPath}`;
+  const response = await fetchImpl(url, { headers: githubHeaders(token) });
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.json())?.message || "";
+    } catch {
+      detail = "";
+    }
+    throw new Error(`GitHub artifact download ${requestPath} failed with ${response.status}${detail ? `: ${detail}` : ""}`);
+  }
+  fs.writeFileSync(outputPath, Buffer.from(await response.arrayBuffer()));
+  return outputPath;
+}
+
+export function selectMergedChannelPullRequest({ pullRequests = [], targetRef, repository }) {
+  const normalizedTarget = normalizeBranch(targetRef);
+  const candidates = pullRequests.filter((pr) => {
+    const baseRef = normalizeBranch(pr.base?.ref || pr.baseRefName || "");
+    const merged = Boolean(pr.merged_at || pr.mergedAt || pr.state === "closed");
+    const sameRepo = !repository || !pr.head?.repo?.full_name || pr.head.repo.full_name === repository;
+    return merged && sameRepo && baseRef === normalizedTarget;
+  });
+  candidates.sort((left, right) => {
+    const leftTime = Date.parse(left.merged_at || left.updated_at || left.closed_at || "");
+    const rightTime = Date.parse(right.merged_at || right.updated_at || right.closed_at || "");
+    return (rightTime || 0) - (leftTime || 0);
+  });
+  return candidates[0];
+}
+
+export function selectReleaseCandidateRun({ runs = [], pullRequest, workflowName = "Build Surface Fixture" }) {
+  const prNumber = Number(pullRequest?.number || 0);
+  const candidates = runs.filter((run) => {
+    const runPrs = Array.isArray(run.pull_requests) ? run.pull_requests : [];
+    const matchesPr = runPrs.some((pr) => Number(pr.number || 0) === prNumber);
+    const matchesWorkflow = !workflowName || run.name === workflowName || run.display_title === workflowName;
+    return matchesPr && matchesWorkflow && run.event === "pull_request" && run.status === "completed" && run.conclusion === "success";
+  });
+  candidates.sort((left, right) => Date.parse(right.updated_at || right.created_at || "") - Date.parse(left.updated_at || left.created_at || ""));
+  return candidates[0];
+}
+
+export function selectReleaseCandidateArtifacts({ artifacts = [] }) {
+  const active = artifacts.filter((artifact) => !artifact.expired);
+  const passports = active.filter((artifact) => /-release-candidate-[0-9a-f]{40}$/i.test(artifact.name || ""));
+  if (passports.length !== 1) {
+    throw new Error(`expected exactly one release-candidate passport artifact, found ${passports.length}`);
+  }
+  const passport = passports[0];
+  const match = passport.name.match(/^(.+)-release-candidate-([0-9a-f]{40})$/i);
+  const prefix = match?.[1] || "";
+  const sha = match?.[2] || "";
+  const summaries = active.filter((artifact) => artifact.name === `${prefix}-summary-${sha}`);
+  if (summaries.length !== 1) {
+    throw new Error(`expected exactly one build summary artifact named ${prefix}-summary-${sha}, found ${summaries.length}`);
+  }
+  return { passport, summary: summaries[0], prefix, sourceSha: sha };
+}
+
+function unzip(zipPath, outputDir) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  execFileSync("unzip", ["-q", "-o", zipPath, "-d", outputDir], { stdio: "inherit" });
+}
+
+function findDownloadedFile(root, filename) {
+  const stack = [root];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.name === filename) {
+        return fullPath;
+      }
+    }
+  }
+  return "";
+}
+
+export async function resolveReleaseCandidateArtifacts({
+  repository,
+  targetRef,
+  targetSha,
+  token = env("GITHUB_TOKEN"),
+  apiUrl = env("GITHUB_API_URL", "https://api.github.com"),
+  workflowFile = DEFAULT_WORKFLOW_FILE,
+  workflowName = "Build Surface Fixture",
+  outputDir = ".buildchain/release-candidate",
+  fetchImpl = globalThis.fetch,
+  download = true,
+} = {}) {
+  const repoInfo = splitRepository(repository);
+  const sha = assertSha(targetSha, "targetSha");
+  const normalizedTarget = normalizeBranch(targetRef);
+  if (!/^(alpha|release)\/v\d+\/v\d+\.\d+$/.test(normalizedTarget)) {
+    return {
+      enabled: false,
+      reason: `target ref ${normalizedTarget || "(empty)"} does not require release-candidate promotion`,
+    };
+  }
+  const pulls = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/commits/${sha}/pulls`,
+  });
+  const pullRequest = selectMergedChannelPullRequest({
+    pullRequests: Array.isArray(pulls) ? pulls : [],
+    targetRef: normalizedTarget,
+    repository: repoInfo.fullName,
+  });
+  if (!pullRequest) {
+    throw new Error(`no same-repository merged channel PR found for ${sha} into ${normalizedTarget}`);
+  }
+  const runs = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/workflows/${encodeURIComponent(workflowFile)}/runs?event=pull_request&status=success&per_page=100`,
+  });
+  const run = selectReleaseCandidateRun({
+    runs: Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [],
+    pullRequest,
+    workflowName,
+  });
+  if (!run) {
+    throw new Error(`no successful ${workflowName} pull_request run found for channel PR #${pullRequest.number}`);
+  }
+  const artifactResponse = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${run.id}/artifacts?per_page=100`,
+  });
+  const selected = selectReleaseCandidateArtifacts({
+    artifacts: Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [],
+  });
+  const result = {
+    enabled: true,
+    repository: repoInfo.fullName,
+    targetRef: normalizedTarget,
+    targetSha: sha,
+    pullRequest: {
+      number: pullRequest.number,
+      url: pullRequest.html_url || pullRequest.url || "",
+      headRef: pullRequest.head?.ref || "",
+      baseRef: pullRequest.base?.ref || "",
+    },
+    run: {
+      id: String(run.id || ""),
+      url: run.html_url || run.url || "",
+      name: run.name || workflowName,
+    },
+    artifacts: {
+      passport: selected.passport.name,
+      summary: selected.summary.name,
+      sourceSha: selected.sourceSha,
+    },
+  };
+  if (!download) {
+    return result;
+  }
+  const resolvedOutput = path.resolve(outputDir);
+  fs.mkdirSync(resolvedOutput, { recursive: true });
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-rc-"));
+  const passportDir = path.join(resolvedOutput, "passport");
+  const summaryDir = path.join(resolvedOutput, "summary");
+  const passportZip = path.join(tempDir, "passport.zip");
+  const summaryZip = path.join(tempDir, "summary.zip");
+  await githubDownload({
+    apiUrl,
+    token,
+    fetchImpl,
+    outputPath: passportZip,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/artifacts/${selected.passport.id}/zip`,
+  });
+  await githubDownload({
+    apiUrl,
+    token,
+    fetchImpl,
+    outputPath: summaryZip,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/artifacts/${selected.summary.id}/zip`,
+  });
+  unzip(passportZip, passportDir);
+  unzip(summaryZip, summaryDir);
+  fs.rmSync(tempDir, { recursive: true, force: true });
+  const passportPath = findDownloadedFile(passportDir, "release-candidate-passport.json");
+  const buildSummaryPath = findDownloadedFile(summaryDir, "build-summary.json");
+  if (!passportPath || !buildSummaryPath) {
+    throw new Error("downloaded release-candidate artifacts did not contain release-candidate-passport.json and build-summary.json");
+  }
+  const passport = JSON.parse(fs.readFileSync(passportPath, "utf8"));
+  return {
+    ...result,
+    paths: {
+      passport: path.relative(process.cwd(), passportPath).split(path.sep).join("/"),
+      buildSummary: path.relative(process.cwd(), buildSummaryPath).split(path.sep).join("/"),
+    },
+    version: passport.target?.version || "",
+    candidateHash: passport.candidateHash || "",
+  };
+}
+
+export async function resolveReleaseCandidateArtifactsCli() {
+  const result = await resolveReleaseCandidateArtifacts({
+    repository: env("BUILDCHAIN_SOURCE_REPOSITORY", env("GITHUB_REPOSITORY")),
+    targetRef: env("BUILDCHAIN_TARGET_REF"),
+    targetSha: env("BUILDCHAIN_TARGET_SHA"),
+    workflowFile: env("BUILDCHAIN_RC_WORKFLOW_FILE", DEFAULT_WORKFLOW_FILE),
+    workflowName: env("BUILDCHAIN_RC_WORKFLOW_NAME", "Build Surface Fixture"),
+    outputDir: env("BUILDCHAIN_RC_OUTPUT_DIR", ".buildchain/release-candidate"),
+  });
+  writeGitHubOutputs({
+    "promote-only-release-candidate": String(result.enabled === true),
+    "release-candidate-passport-path": result.paths?.passport || "",
+    "release-candidate-build-summary-path": result.paths?.buildSummary || "",
+    "release-candidate-version": result.version || "",
+    "release-candidate-artifact": result.artifacts?.passport || "",
+    "release-candidate-build-summary-artifact": result.artifacts?.summary || "",
+    "release-candidate-run-id": result.run?.id || "",
+    "release-candidate-run-url": result.run?.url || "",
+    "release-candidate-pr": result.pullRequest?.number ? String(result.pullRequest.number) : "",
+    "release-candidate-diagnosis": result.enabled
+      ? `Resolved PR-stage RC passport ${result.artifacts.passport} from ${result.run.url || `run ${result.run.id}`}`
+      : result.reason || "",
+  });
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    await resolveReleaseCandidateArtifactsCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/workflow-friction-report.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+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";
+
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function splitRepository(repository) {
+  const match = String(repository || "").trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(`repository must be owner/repo, got ${repository || "<empty>"}`);
+  }
+  return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };
+}
+
+function normalizeBranch(value = "") {
+  return String(value || "").replace(/^refs\/heads\//, "").trim();
+}
+
+function assertSha(value, label = "sha") {
+  const sha = String(value || "").trim();
+  if (!/^[0-9a-f]{40}$/i.test(sha)) {
+    throw new Error(`${label} must be a 40-character Git SHA`);
+  }
+  return sha;
+}
+
+function githubHeaders(token) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "buildchain-workflow-friction-report",
+    "x-github-api-version": "2022-11-28",
+  };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+async function githubJson({ apiUrl, token, path: requestPath, fetchImpl = globalThis.fetch }) {
+  const url = `${String(apiUrl || "https://api.github.com").replace(/\/+$/, "")}${requestPath}`;
+  const response = await fetchImpl(url, { headers: githubHeaders(token) });
+  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}`);
+  }
+  return body;
+}
+
+function runLabel(run = "") {
+  if (typeof run === "string") {
+    return run;
+  }
+  const title = run.display_title || run.name || "workflow run";
+  const url = run.html_url || run.url || "";
+  const status = [run.status, run.conclusion].filter(Boolean).join("/");
+  return `${title}${status ? ` (${status})` : ""}${url ? ` ${url}` : ""}`;
+}
+
+export function selectFrictionClass({
+  duplicatePullRequests = [],
+  heavyBuilds = [],
+  releaseCandidateOutcome = "",
+} = {}) {
+  if (duplicatePullRequests.length > 1) {
+    return "duplicate-channel-pr";
+  }
+  if (heavyBuilds.length > 1) {
+    return "duplicate-heavy-build";
+  }
+  if (releaseCandidateOutcome === "failure") {
+    return "late-fail-fast";
+  }
+  return "buildchain-ref-promotion-failed";
+}
+
+export function buildWorkflowFrictionBody({
+  repository,
+  targetRef,
+  targetSha,
+  runUrl,
+  pullRequests = [],
+  heavyBuilds = [],
+  relatedRuns = [],
+  frictionClass,
+  diagnosis,
+  nextAction,
+  releaseCandidateDiagnosis = "",
+} = {}) {
+  return [
+    "# Buildchain workflow friction evidence",
+    "",
+    "## Promotion context",
+    "",
+    `- Repository: ${repository || "(unknown)"}`,
+    `- Target ref: ${targetRef || "(unknown)"}`,
+    `- Target SHA: ${targetSha || "(unknown)"}`,
+    `- Promotion run: ${runUrl || "(unknown)"}`,
+    `- Friction class: ${frictionClass || "(unknown)"}`,
+    releaseCandidateDiagnosis ? `- RC resolver: ${releaseCandidateDiagnosis}` : "",
+    "",
+    pullRequests.length
+      ? `## Associated PRs\n\n${pullRequests.map((pr) => `- #${pr.number} ${pr.title || ""} ${pr.html_url || pr.url || ""}`).join("\n")}`
+      : "## Associated PRs\n\n- (none detected)",
+    "",
+    relatedRuns.length
+      ? `## Related workflow runs\n\n${relatedRuns.map((run) => `- ${runLabel(run)}`).join("\n")}`
+      : "## Related workflow runs\n\n- (none detected)",
+    "",
+    heavyBuilds.length
+      ? `## Heavy build runs\n\n${heavyBuilds.map((run) => `- ${runLabel(run)}`).join("\n")}`
+      : "## Heavy build runs\n\n- (none detected)",
+    "",
+    diagnosis ? `## Diagnosis\n\n${diagnosis}` : "",
+    nextAction ? `## Suggested next action\n\n${nextAction}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+export async function classifyWorkflowFriction({
+  repository,
+  targetRef,
+  targetSha,
+  token = env("GITHUB_TOKEN"),
+  apiUrl = env("GITHUB_API_URL", "https://api.github.com"),
+  buildWorkflowFile = DEFAULT_BUILD_WORKFLOW_FILE,
+  releaseCandidateOutcome = env("BUILDCHAIN_RC_RESOLVE_OUTCOME"),
+  releaseCandidateDiagnosis = env("BUILDCHAIN_RC_DIAGNOSIS"),
+  runUrl = env("BUILDCHAIN_WORKFLOW_RUN_URL"),
+  outputDir = ".buildchain/workflow-friction",
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const repo = splitRepository(repository);
+  const sha = assertSha(targetSha, "targetSha");
+  const normalizedTarget = normalizeBranch(targetRef);
+  const pullResponse = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repo.owner}/${repo.repo}/commits/${sha}/pulls`,
+  });
+  const pullRequests = (Array.isArray(pullResponse) ? pullResponse : [])
+    .filter((pr) => normalizeBranch(pr.base?.ref || "") === normalizedTarget)
+    .filter((pr) => !pr.head?.repo?.full_name || pr.head.repo.full_name === repo.fullName);
+  const primaryPullRequest = pullRequests
+    .filter((pr) => pr.merged_at || pr.state === "closed")
+    .sort((left, right) => Date.parse(right.updated_at || right.merged_at || "") - Date.parse(left.updated_at || left.merged_at || ""))[0]
+    || pullRequests[0];
+
+  let relatedRuns = [];
+  let heavyBuilds = [];
+  if (primaryPullRequest?.number) {
+    const runs = await githubJson({
+      apiUrl,
+      token,
+      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 : [])
+      .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 || ""));
+  }
+
+  const frictionClass = selectFrictionClass({
+    duplicatePullRequests: pullRequests,
+    heavyBuilds,
+    releaseCandidateOutcome,
+  });
+  const diagnosisParts = [];
+  if (pullRequests.length > 1) {
+    diagnosisParts.push(`Detected ${pullRequests.length} channel PRs associated with the same promoted SHA.`);
+  }
+  if (heavyBuilds.length > 1) {
+    diagnosisParts.push(`Detected ${heavyBuilds.length} completed PR-stage heavy build runs for PR #${primaryPullRequest?.number}.`);
+  }
+  if (releaseCandidateOutcome === "failure") {
+    diagnosisParts.push("Promotion reached the post-Verify workflow before required PR-stage RC evidence could be resolved.");
+  }
+  if (releaseCandidateDiagnosis) {
+    diagnosisParts.push(releaseCandidateDiagnosis);
+  }
+  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."
+    : "Deduplicate the PR/build path or tighten Buildchain workflow gates so the next channel promotion reaches publish exactly once.";
+  fs.mkdirSync(outputDir, { recursive: true });
+  const bodyFile = path.join(outputDir, "issue-body.md");
+  const body = buildWorkflowFrictionBody({
+    repository: repo.fullName,
+    targetRef: normalizedTarget,
+    targetSha: sha,
+    runUrl,
+    pullRequests,
+    heavyBuilds,
+    relatedRuns,
+    frictionClass,
+    diagnosis,
+    nextAction,
+    releaseCandidateDiagnosis,
+  });
+  fs.writeFileSync(bodyFile, `${body}\n`);
+  return {
+    frictionClass,
+    summary: `Buildchain ref promotion failed after Verify with ${frictionClass} evidence.`,
+    diagnosis,
+    nextAction,
+    pullRequest: primaryPullRequest?.number ? `#${primaryPullRequest.number}` : "",
+    bodyFile,
+    relatedRuns: relatedRuns.map(runLabel),
+    heavyBuilds: heavyBuilds.map((run) => ({
+      name: runLabel(run),
+      durationMs: run.run_started_at && run.updated_at
+        ? Math.max(0, Date.parse(run.updated_at) - Date.parse(run.run_started_at))
+        : "",
+    })),
+  };
+}
+
+export async function workflowFrictionReportCli() {
+  let result;
+  try {
+    result = await classifyWorkflowFriction({
+      repository: env("BUILDCHAIN_SOURCE_REPOSITORY", env("GITHUB_REPOSITORY")),
+      targetRef: env("BUILDCHAIN_TARGET_REF"),
+      targetSha: env("BUILDCHAIN_TARGET_SHA"),
+      buildWorkflowFile: env("BUILDCHAIN_BUILD_WORKFLOW_FILE", DEFAULT_BUILD_WORKFLOW_FILE),
+      outputDir: env("BUILDCHAIN_FRICTION_OUTPUT_DIR", ".buildchain/workflow-friction"),
+    });
+  } catch (error) {
+    const outputDir = env("BUILDCHAIN_FRICTION_OUTPUT_DIR", ".buildchain/workflow-friction");
+    fs.mkdirSync(outputDir, { recursive: true });
+    const bodyFile = path.join(outputDir, "issue-body.md");
+    const diagnosis = `Workflow friction auto-classification failed: ${error.message}`;
+    result = {
+      frictionClass: env("BUILDCHAIN_RC_RESOLVE_OUTCOME") === "failure" ? "late-fail-fast" : "buildchain-ref-promotion-failed",
+      summary: "Buildchain ref promotion failed after Verify; auto-classification did not complete.",
+      diagnosis,
+      nextAction: "Inspect the promotion logs and fix the Buildchain workflow contract so this class of failure is reported before repeated heavy work or publish side effects.",
+      pullRequest: "",
+      bodyFile,
+      relatedRuns: [],
+      heavyBuilds: [],
+    };
+    fs.writeFileSync(bodyFile, `${buildWorkflowFrictionBody({
+      repository: env("BUILDCHAIN_SOURCE_REPOSITORY", env("GITHUB_REPOSITORY")),
+      targetRef: env("BUILDCHAIN_TARGET_REF"),
+      targetSha: env("BUILDCHAIN_TARGET_SHA"),
+      runUrl: env("BUILDCHAIN_WORKFLOW_RUN_URL"),
+      frictionClass: result.frictionClass,
+      diagnosis,
+      nextAction: result.nextAction,
+      releaseCandidateDiagnosis: env("BUILDCHAIN_RC_DIAGNOSIS"),
+    })}\n`);
+    console.error(`::warning::${diagnosis.replace(/\r?\n/g, "%0A")}`);
+  }
+  writeGitHubOutputs({
+    "friction-class": result.frictionClass,
+    summary: result.summary,
+    diagnosis: result.diagnosis,
+    "next-action": result.nextAction,
+    "pull-request": result.pullRequest,
+    "body-file": result.bodyFile,
+    "related-runs-json": JSON.stringify(result.relatedRuns),
+    "heavy-builds-json": JSON.stringify(result.heavyBuilds),
+  });
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await workflowFrictionReportCli();
+}