@kungfu-tech/buildchain 2.10.4 → 2.10.5

package/packages/core/public-surface-audit.js

@@ -40,9 +40,11 @@ function listDirectories(root, dir) {
     .sort();
 }
 
-function commandId(first = "", second = "") {
+function commandId(first = "", second = "", third = "") {
   const head = String(first || "").trim();
   const sub = String(second || "").trim();
+  const leaf = String(third || "").trim();
+  const normalizedLeaf = leaf === "..." ? "" : leaf;
   if (!head) return "";
   if (["-h", "--help", "help"].includes(head)) return "help";
   if (["-v", "--version", "version"].includes(head)) return "version";
@@ -59,7 +61,12 @@ function commandId(first = "", second = "") {
   if (head === "log" && sub) return "logging";
   if (head === "diagnostics" && sub) return `diagnostics-${sub}`;
   if (head === "facts" && sub) return "build-facts";
-  if (head === "kfd-3" && sub) return `kfd-3-${sub}`;
+  if (head === "kfd") {
+    if (!sub || sub === "...") return "kfd";
+    if (sub === "schema") return normalizedLeaf ? `kfd-schema-${normalizedLeaf}` : "kfd-schema";
+    if (/^[1-9][0-9]*$/.test(sub)) return normalizedLeaf ? `kfd-${sub}-${normalizedLeaf}` : `kfd-${sub}`;
+    return `kfd-${sub}`;
+  }
   if (head === "sample" && sub) return `sample-${sub}`;
   if (head === "badges" && sub) return `badges-${sub}`;
   if (head === "homebrew" && sub) return `homebrew-${sub}`;
@@ -77,10 +84,10 @@ export function enumerateCliCommandsFromBin({ root = process.cwd(), binPath = "b
   const usage = usageMatch?.[1] || "";
   const usageCommands = [];
   for (const line of usage.split(/\r?\n/)) {
-    const match = line.trim().match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?/);
+    const match = line.trim().match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?(?:\s+([^\s]+))?/);
     if (!match) continue;
     usageCommands.push({
-      id: commandId(match[1], match[2]),
+      id: commandId(match[1], match[2], match[3]),
       usage: line.trim().replace(/\s+/g, " "),
     });
   }
@@ -180,15 +187,15 @@ export function enumerateDocCommandRefs({ root = process.cwd() } = {}) {
             .filter((line) => /^(?:[$>]\s*)?(?:npx\s+(?:@kungfu-tech\/buildchain|buildchain)\s+|node\s+bin\/buildchain\.mjs\s+|buildchain\s+)/.test(line))
             .join("\n")
         : segment.text;
-      for (const match of commandText.matchAll(/(?:^|[\s$>])(?:npx\s+(?:@kungfu-tech\/buildchain|buildchain)\s+|node\s+bin\/buildchain\.mjs\s+|buildchain\s+)([a-z0-9][a-z0-9-]*|--help|--version|-h|-v)(?:\s+([a-z0-9][a-z0-9-]*|--[a-z0-9-]+))?/gm)) {
-        const id = commandId(match[1], match[2]);
+      for (const match of commandText.matchAll(/(?:^|[\s$>])(?:npx\s+(?:@kungfu-tech\/buildchain|buildchain)\s+|node\s+bin\/buildchain\.mjs\s+|buildchain\s+)([a-z0-9][a-z0-9-]*|--help|--version|-h|-v)(?:\s+([a-z0-9][a-z0-9-]*|--[a-z0-9-]+))?(?:\s+([a-z0-9][a-z0-9-]*|--[a-z0-9-]+))?/gm)) {
+        const id = commandId(match[1], match[2], match[3]);
         if (segment.kind === "inline" && !knownCommandIds.has(id)) {
           continue;
         }
         refs.push({
           id,
           path: relPath,
-          command: `buildchain ${match[1]}${match[2] ? ` ${match[2]}` : ""}`,
+          command: `buildchain ${match[1]}${match[2] ? ` ${match[2]}` : ""}${match[3] ? ` ${match[3]}` : ""}`,
         });
       }
     }

package/scripts/buildchain-contract-lock.mjs

@@ -10,6 +10,10 @@ import {
   readBuildchainContractWorld,
   renderBuildchainContractDriftIssueBody,
 } from "../packages/core/buildchain-contract.js";
+import {
+  BUILDCHAIN_CONTRACT_LOCK_PATH,
+  resolveBuildchainContractLockPath,
+} from "../packages/core/buildchain-layout.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
 function env(name, fallback = "") {
@@ -58,7 +62,7 @@ function issueModeAllows(mode, evaluation) {
 }
 
 export function checkBuildchainContractLock({
-  lockPath = env("BUILDCHAIN_CONTRACT_LOCK_PATH", "buildchain.contract-lock.json"),
+  lockPath = env("BUILDCHAIN_CONTRACT_LOCK_PATH") || resolveBuildchainContractLockPath(process.cwd()),
   currentContractPath = env("BUILDCHAIN_CONTRACT_CURRENT_PATH", ".buildchain/runtime/dist/site/buildchain-contract.json"),
   runtimeRoot = env("BUILDCHAIN_RUNTIME_ROOT", ".buildchain/runtime"),
   runtimeRef = env("BUILDCHAIN_RUNTIME_REF"),
@@ -124,7 +128,7 @@ export function checkBuildchainContractLock({
 }
 
 export function writeBuildchainContractLock({
-  output = env("BUILDCHAIN_CONTRACT_LOCK_PATH", "buildchain.contract-lock.json"),
+  output = env("BUILDCHAIN_CONTRACT_LOCK_PATH", BUILDCHAIN_CONTRACT_LOCK_PATH),
   currentContractPath = env("BUILDCHAIN_CONTRACT_CURRENT_PATH", "dist/site/buildchain-contract.json"),
   runtimeRoot = env("BUILDCHAIN_RUNTIME_ROOT", process.cwd()),
   buildchainRef = env("BUILDCHAIN_RUNTIME_REF", "v2"),

package/scripts/check-inventory.mjs

@@ -54,7 +54,8 @@ const requiredPaths = [
   "docs/lifecycle-protocol.md",
   "docs/ownership.md",
   "tests/buildchain-inventory.json",
-  "buildchain.toml",
+  ".buildchain/buildchain.toml",
+  ".buildchain/contract-lock.json",
   ".github/actionlint.yaml",
   ".github/workflows/self-hosted-runner-smoke.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
@@ -126,8 +127,8 @@ if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildcha
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
-if (rootPackage.exports?.["./kfd-3-surfaces"] !== "./packages/core/kfd3-surface-register.js") {
-  throw new Error("root package must export @kungfu-tech/buildchain/kfd-3-surfaces");
+if (rootPackage.exports?.["./kfd"] !== "./packages/core/kfd.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/kfd");
 }
 if (rootPackage.exports?.["./release-line-bootstrap"] !== "./packages/core/release-line-bootstrap.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-line-bootstrap");
@@ -498,7 +499,7 @@ for (const requiredSnippet of [
   "buildFacts[]",
   "--build-facts-json",
   "Floating Buildchain contract lock",
-  "buildchain.contract-lock.json",
+  ".buildchain/contract-lock.json",
   "--kfd-3-prebuild-witness-json",
   "--kfd-3-artifact-verify-cmd",
   "currently named `kfd-3`",

package/scripts/generate-site-bundle.mjs

@@ -388,12 +388,28 @@ function cliCommandMeta(id) {
     inspect: { group: "release-passport-trust", purpose: "Inspect release and artifact evidence command families." },
     "inspect-artifact": { group: "release-passport-trust", purpose: "Inspect artifact evidence." },
     "inspect-release": { group: "release-passport-trust", purpose: "Inspect release passport evidence." },
-    "kfd-3": { group: "kfd-trust", purpose: "Inspect KFD-3 surface detection, registry, witness, audit, and query command families." },
+    kfd: { group: "kfd-trust", purpose: "Inspect KFD standards, schemas, and versioned KFD command families." },
+    "kfd-schema": { group: "kfd-trust", purpose: "Inspect KFD schema command families." },
+    "kfd-schema-list": { group: "kfd-trust", purpose: "List machine-readable schemas exposed by the KFD package standards metadata." },
+    "kfd-schema-show": { group: "kfd-trust", purpose: "Print a machine-readable KFD schema from the KFD package standards metadata." },
+    "kfd-status": { group: "kfd-trust", purpose: "Report implemented KFD support and the active .buildchain repository layout." },
+    "kfd-migrate-layout": { group: "kfd-trust", purpose: "Plan or apply migration of legacy root Buildchain files into .buildchain/." },
+    "kfd-1": { group: "kfd-trust", purpose: "Inspect KFD-1 contract-world witness, gate, verify, and schema command families." },
+    "kfd-1-gate": { group: "kfd-trust", purpose: "Generate KFD-1 release gate evidence from declared contract-world witnesses." },
+    "kfd-1-schema": { group: "kfd-trust", purpose: "Print the default KFD-1 schema exposed by the KFD package standards metadata." },
+    "kfd-1-verify": { group: "kfd-trust", purpose: "Validate KFD-1 release gate evidence." },
+    "kfd-1-witness": { group: "kfd-trust", purpose: "Generate Buildchain's KFD-1 self contract-world witness." },
+    "kfd-2": { group: "kfd-trust", purpose: "Inspect KFD-2 trust taxonomy, public claims, and schema command families." },
+    "kfd-2-claims": { group: "kfd-trust", purpose: "Generate Buildchain's KFD-2 public trust claim evidence." },
+    "kfd-2-schema": { group: "kfd-trust", purpose: "Print the default KFD-2 schema exposed by the KFD package standards metadata." },
+    "kfd-2-taxonomy": { group: "kfd-trust", purpose: "Validate KFD-2 trust taxonomy entries from the KFD package standards metadata." },
+    "kfd-3": { group: "kfd-trust", purpose: "Inspect KFD-3 surface detection, registry, witness, audit, and query command families under the unified KFD namespace." },
     "kfd-3-audit": { group: "kfd-trust", purpose: "Compare detected, declared, and enforced KFD-3 public surfaces." },
     "kfd-3-detect": { group: "kfd-trust", purpose: "Detect standard KFD-3 public surface candidates from source and artifact metadata." },
     "kfd-3-query": { group: "kfd-trust", purpose: "Return an agent-readable KFD-3 capability map for a product, registry, or release passport." },
     "kfd-3-register": { group: "kfd-trust", purpose: "Declare detected KFD-3 public surfaces into a product-owned surface registry." },
     "kfd-3-witness": { group: "kfd-trust", purpose: "Generate release-passport-compatible KFD-3 surface witnesses from a product registry." },
+    "kfd-4-schema": { group: "kfd-trust", purpose: "Print the default KFD-4 schema exposed by the KFD package standards metadata." },
     lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
     log: { group: "observability-diagnostics", purpose: "Inspect Buildchain logging command families." },
     logging: { group: "observability-diagnostics", purpose: "Emit timestamped build events, summarize logs, and enforce required phases." },
@@ -409,7 +425,7 @@ function cliCommandMeta(id) {
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
     span: { group: "observability-diagnostics", purpose: "Run a command inside a Buildchain log span." },
     "transaction-inspect": { group: "release-passport-trust", purpose: "Inspect durable release transaction state." },
-    validate: { group: "getting-started", purpose: "Validate buildchain.toml and declared lifecycle surfaces." },
+    validate: { group: "getting-started", purpose: "Validate .buildchain/buildchain.toml and declared lifecycle surfaces." },
     verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
     "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
     "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
@@ -443,7 +459,8 @@ function nodeApiMeta(exportName) {
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },
-    "./kfd-3-surfaces": { group: "kfd-trust", summary: "KFD-3 detection, registration, audit, witness, and capability query APIs." },
+    "./buildchain-layout": { group: "kfd-trust", summary: "Canonical .buildchain repository layout constants, path resolution, and migration APIs." },
+    "./kfd": { group: "kfd-trust", summary: "Unified KFD standards, schema discovery, KFD-1/KFD-2/KFD-3 grouped APIs, KFD-4 schema discovery, and Buildchain KFD claim helpers." },
     "./public-surface-audit": { group: "kfd-trust", summary: "Reverse audit APIs for CLI, workflow, action, site page, and documentation command surfaces." },
     "./kfd-gate": { group: "kfd-trust", summary: "KFD-1/KFD-2/KFD-3 release gate evidence and validation APIs." },
     "./buildchain-kfd-claims": { group: "kfd-trust", summary: "Buildchain self KFD claim registry, witnesses, and public claim APIs." },

package/scripts/init-repo.mjs

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { BUILDCHAIN_CONFIG_PATH } from "../packages/core/buildchain-layout.js";
 import { detectPackageManager, assertPackageManager } from "../packages/core/package-manager.js";
 
 const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v2";
@@ -356,7 +357,7 @@ export function initBuildchainRepo({
   })();
 
   const written = [
-    writeIfAllowed(path.join(resolvedCwd, "buildchain.toml"), toml, { force }),
+    writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
     writeIfAllowed(path.join(resolvedCwd, ".github", "workflows", "build.yml"), workflowYaml({
       type,
       runnerPreset,

package/scripts/web-surface-production-release-pr.mjs

@@ -30,6 +30,14 @@ function parseJson(value, name) {
   }
 }
 
+function parseBoolean(value, defaultValue = false) {
+  const normalized = optionalString(value).toLowerCase();
+  if (!normalized) return defaultValue;
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new Error(`expected boolean value, got: ${value}`);
+}
+
 function readArg(name, fallback = "") {
   const index = process.argv.indexOf(`--${name}`);
   if (index === -1) return fallback;
@@ -51,6 +59,12 @@ function writeJsonFile(filePath, value) {
   fs.writeFileSync(resolved, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function writeTextFile(filePath, value) {
+  const resolved = path.resolve(requiredString(filePath, "filePath"));
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, String(value));
+}
+
 function runUrl({ serverUrl = "", repository = "", runId = "" } = {}) {
   if (!serverUrl || !repository || !runId) return "";
   return `${serverUrl.replace(/\/$/, "")}/${repository}/actions/runs/${runId}`;
@@ -153,6 +167,113 @@ ${urlLines.join("\n")}
 This PR intentionally contains one empty release-intent commit.`;
 }
 
+export function createProductionReleasePrHandoff({
+  repository,
+  sourceSha,
+  stagingResult = {},
+  productionReleaseLabel = "buildchain-release",
+  productionReleaseHeadPrefix = "release/",
+  productionReleaseChannel = "production",
+  runId = "",
+  serverUrl = "https://github.com",
+  releasePassportArtifact = "buildchain-web-surface-staging-release-passport",
+} = {}) {
+  const [owner, repo] = requiredString(repository, "repository").split("/");
+  if (!owner || !repo) throw new Error(`invalid repository: ${repository}`);
+  const normalizedSourceSha = requiredString(sourceSha, "sourceSha");
+  const label = requiredString(productionReleaseLabel, "productionReleaseLabel");
+  const branchName = releaseBranchName({
+    prefix: productionReleaseHeadPrefix || "release/",
+    channel: productionReleaseChannel || "production",
+    sourceSha: normalizedSourceSha,
+  });
+  const workflowRunUrl = runUrl({ serverUrl, repository, runId });
+  const title = `Release production from ${normalizedSourceSha.slice(0, 12)}`;
+  const body = renderProductionReleasePrBody({
+    stagingResult,
+    sourceSha: normalizedSourceSha,
+    artifactHash: stagingResult.artifactHash || "",
+    releasePassportArtifact,
+    workflowRunUrl,
+    productionReleaseLabel: label,
+    branchName,
+  });
+  const emptyCommitMessage = `buildchain release intent: ${productionReleaseChannel} ${normalizedSourceSha.slice(0, 12)}`;
+  const bodyPath = ".buildchain/production-release-pr/body.md";
+  const manualCommand = [
+    "git fetch origin main",
+    `git switch -C ${branchName} ${normalizedSourceSha}`,
+    `git commit --allow-empty -m ${JSON.stringify(emptyCommitMessage)}`,
+    `git push origin HEAD:${branchName}`,
+    `gh pr create --repo ${repository} --base main --head ${branchName} --title ${JSON.stringify(title)} --body-file ${bodyPath}`,
+  ].join(" && ");
+  return {
+    contract: "kungfu-buildchain-web-surface-production-release-pr-handoff",
+    schemaVersion: 1,
+    repository,
+    owner,
+    repo,
+    base: "main",
+    head: `${owner}:${branchName}`,
+    branchName,
+    sourceSha: normalizedSourceSha,
+    title,
+    body,
+    label,
+    productionReleaseChannel,
+    releasePassportArtifact,
+    workflowRunUrl,
+    manualCommand,
+    staging: {
+      channel: stagingResult.channel || "",
+      status: stagingResult.status || "",
+      urls: urlsFromResult(stagingResult),
+      artifactHash: stagingResult.artifactHash || "",
+      target: stagingResult.target || "",
+      manifestKey: stagingResult.manifestKey || "",
+    },
+  };
+}
+
+function classifyReleasePrError(error) {
+  const message = String(error?.message || error || "");
+  if (
+    error?.status === 403 &&
+    /not permitted to create or approve pull requests|Resource not accessible by integration|permission|forbidden/i.test(message)
+  ) {
+    return "permission-denied";
+  }
+  return "failed";
+}
+
+function renderStepSummary(result = {}) {
+  const status = result.status || result.action || "unknown";
+  const lines = [
+    "## Buildchain production release PR handoff",
+    "",
+    `- status: \`${status}\``,
+    `- mode: \`${result.mode || "auto"}\``,
+    `- source: \`${result.sourceSha || ""}\``,
+    `- release branch: \`${result.branchName || ""}\``,
+  ];
+  if (result.pullUrl) lines.push(`- pull request: ${result.pullUrl}`);
+  if (result.error?.message) lines.push(`- error: \`${result.error.message.replace(/`/g, "'")}\``);
+  if (result.manualCommand) {
+    lines.push("", "Manual PR creation command:", "", "```bash", result.manualCommand, "```");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function writeGitHubOutputs(env, outputs) {
+  for (const [name, value] of Object.entries(outputs)) {
+    const normalized = String(value ?? "");
+    console.log(`${name}=${normalized}`);
+    if (env.GITHUB_OUTPUT) {
+      fs.appendFileSync(env.GITHUB_OUTPUT, `${name}=${normalized}\n`);
+    }
+  }
+}
+
 async function githubJson({ apiUrl, token, method = "GET", path, body }) {
   const response = await fetch(`${apiUrl.replace(/\/$/, "")}${path}`, {
     method,
@@ -264,28 +385,19 @@ export async function openProductionReleasePr({
   serverUrl = "https://github.com",
   releasePassportArtifact = "buildchain-web-surface-staging-release-passport",
 } = {}) {
-  const [owner, repo] = requiredString(repository, "repository").split("/");
-  if (!owner || !repo) throw new Error(`invalid repository: ${repository}`);
-  const normalizedToken = requiredString(token, "token");
-  const normalizedSourceSha = requiredString(sourceSha, "sourceSha");
-  const label = requiredString(productionReleaseLabel, "productionReleaseLabel");
-  const branchName = releaseBranchName({
-    prefix: productionReleaseHeadPrefix || "release/",
-    channel: productionReleaseChannel || "production",
-    sourceSha: normalizedSourceSha,
-  });
-  const workflowRunUrl = runUrl({ serverUrl, repository, runId });
-  const body = renderProductionReleasePrBody({
+  const handoff = createProductionReleasePrHandoff({
+    repository,
+    sourceSha,
     stagingResult,
-    sourceSha: normalizedSourceSha,
-    artifactHash: stagingResult.artifactHash || "",
+    productionReleaseLabel,
+    productionReleaseHeadPrefix,
+    productionReleaseChannel,
+    runId,
+    serverUrl,
     releasePassportArtifact,
-    workflowRunUrl,
-    productionReleaseLabel: label,
-    branchName,
   });
-  const title = `Release production from ${normalizedSourceSha.slice(0, 12)}`;
-  const head = `${owner}:${branchName}`;
+  const { owner, repo, branchName, title, body, head } = handoff;
+  const normalizedToken = requiredString(token, "token");
   const existing = await githubJson({
     apiUrl,
     token: normalizedToken,
@@ -300,13 +412,14 @@ export async function openProductionReleasePr({
       path: `/repos/${owner}/${repo}/pulls/${pull.number}`,
       body: { title, body },
     });
-    await addLabel({ apiUrl, token: normalizedToken, owner, repo, pullNumber: pull.number, label });
+    await addLabel({ apiUrl, token: normalizedToken, owner, repo, pullNumber: pull.number, label: handoff.label });
     return {
       action: "updated",
+      status: "updated",
+      ...handoff,
       branchName,
       pullNumber: pull.number,
       pullUrl: pull.html_url,
-      sourceSha: normalizedSourceSha,
     };
   }
 
@@ -316,8 +429,8 @@ export async function openProductionReleasePr({
     owner,
     repo,
     branchName,
-    sourceSha: normalizedSourceSha,
-    message: `buildchain release intent: ${productionReleaseChannel} ${normalizedSourceSha.slice(0, 12)}`,
+    sourceSha: handoff.sourceSha,
+    message: `buildchain release intent: ${productionReleaseChannel} ${handoff.sourceSha.slice(0, 12)}`,
   });
   const pull = await githubJson({
     apiUrl,
@@ -332,23 +445,27 @@ export async function openProductionReleasePr({
       maintainer_can_modify: true,
     },
   });
-  await addLabel({ apiUrl, token: normalizedToken, owner, repo, pullNumber: pull.number, label });
+  await addLabel({ apiUrl, token: normalizedToken, owner, repo, pullNumber: pull.number, label: handoff.label });
   return {
     action: "created",
+    status: "created",
+    ...handoff,
     branchName,
     commitSha,
     pullNumber: pull.number,
     pullUrl: pull.html_url,
-    sourceSha: normalizedSourceSha,
   };
 }
 
 export async function webSurfaceProductionReleasePrCli(env = process.env) {
   const stagingResult = readStagingReleasePrSummary(env);
   const sourceSha = optionalString(stagingResult.sourceSha) || requiredString(env.GITHUB_SHA, "GITHUB_SHA");
-  const result = await openProductionReleasePr({
-    apiUrl: env.GITHUB_API_URL || "https://api.github.com",
-    token: env.GITHUB_TOKEN,
+  const mode = optionalString(env.PRODUCTION_RELEASE_PR_MODE || "auto") || "auto";
+  if (!["auto", "summary-only", "disabled"].includes(mode)) {
+    throw new Error("PRODUCTION_RELEASE_PR_MODE must be auto, summary-only, or disabled");
+  }
+  const failOnReleasePrError = parseBoolean(env.FAIL_ON_RELEASE_PR_ERROR, false);
+  const handoff = createProductionReleasePrHandoff({
     repository: env.GITHUB_REPOSITORY,
     sourceSha,
     stagingResult,
@@ -359,19 +476,75 @@ export async function webSurfaceProductionReleasePrCli(env = process.env) {
     serverUrl: env.GITHUB_SERVER_URL || "https://github.com",
     releasePassportArtifact: env.RELEASE_PASSPORT_ARTIFACT || "buildchain-web-surface-staging-release-passport",
   });
-  for (const [name, value] of Object.entries({
+
+  const bodyPath = optionalString(env.PRODUCTION_RELEASE_PR_BODY_PATH) || ".buildchain/production-release-pr/body.md";
+  const summaryPath = optionalString(env.PRODUCTION_RELEASE_PR_SUMMARY_PATH) || ".buildchain/production-release-pr/handoff.json";
+  writeTextFile(bodyPath, `${handoff.body}\n`);
+
+  let result = {
+    ...handoff,
+    mode,
+    status: mode,
+    action: "skipped",
+    pullNumber: "",
+    pullUrl: "",
+    bodyPath,
+    summaryPath,
+  };
+
+  if (mode === "auto") {
+    try {
+      result = {
+        ...result,
+        ...(await openProductionReleasePr({
+          apiUrl: env.GITHUB_API_URL || "https://api.github.com",
+          token: env.GITHUB_TOKEN,
+          repository: env.GITHUB_REPOSITORY,
+          sourceSha,
+          stagingResult,
+          productionReleaseLabel: env.PRODUCTION_RELEASE_LABEL || "buildchain-release",
+          productionReleaseHeadPrefix: env.PRODUCTION_RELEASE_HEAD_PREFIX || "release/",
+          productionReleaseChannel: env.PRODUCTION_RELEASE_CHANNEL || "production",
+          runId: env.GITHUB_RUN_ID,
+          serverUrl: env.GITHUB_SERVER_URL || "https://github.com",
+          releasePassportArtifact: env.RELEASE_PASSPORT_ARTIFACT || "buildchain-web-surface-staging-release-passport",
+        })),
+        mode,
+      };
+    } catch (error) {
+      const status = classifyReleasePrError(error);
+      result = {
+        ...result,
+        status,
+        action: status,
+        error: {
+          status: error.status || "",
+          message: error.message || String(error),
+        },
+      };
+      if (status !== "permission-denied" || failOnReleasePrError) {
+        writeJsonFile(summaryPath, result);
+        if (env.GITHUB_STEP_SUMMARY) fs.appendFileSync(env.GITHUB_STEP_SUMMARY, renderStepSummary(result));
+        throw error;
+      }
+    }
+  }
+
+  writeJsonFile(summaryPath, result);
+  if (env.GITHUB_STEP_SUMMARY) {
+    fs.appendFileSync(env.GITHUB_STEP_SUMMARY, renderStepSummary(result));
+  }
+  writeGitHubOutputs(env, {
+    "release-pr-status": result.status,
+    "production-release-pr-status": result.status,
     "production-release-pr-action": result.action,
     "production-release-pr": String(result.pullNumber || ""),
     "production-release-pr-url": result.pullUrl || "",
     "production-release-branch": result.branchName || "",
     "production-release-source-sha": result.sourceSha || "",
-  })) {
-    console.log(`${name}=${value}`);
-    if (env.GITHUB_OUTPUT) {
-      const fs = await import("node:fs");
-      fs.appendFileSync(env.GITHUB_OUTPUT, `${name}=${value}\n`);
-    }
-  }
+    "production-release-pr-summary-path": summaryPath,
+    "production-release-pr-body-path": bodyPath,
+  });
   return result;
 }
 

package/scripts/web-surface-release-pr-review.mjs

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
+import { resolveBuildchainConfigPath } from "../packages/core/buildchain-layout.js";
 
 export const RELEASE_REVIEW_MARKER = "<!-- buildchain:web-surface-release-review -->";
 
@@ -51,7 +52,7 @@ export function resolveReleaseReviewState(payload, options = {}) {
 }
 
 export function loadWebSurfaceReleaseUrls(cwd = ".") {
-  const configPath = path.join(cwd, "buildchain.toml");
+  const configPath = path.join(cwd, resolveBuildchainConfigPath(cwd));
   const raw = fs.readFileSync(configPath, "utf8");
   const config = parseToml(raw);
   const stagingUrl = String(config.channels?.staging?.url || "").trim();