@kungfu-tech/buildchain 4.0.1-alpha.4 → 4.0.1-alpha.5

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -20,6 +20,7 @@ import {
   candidateFromDecision,
   selectLatestQualifiedSource,
 } from "../packages/core/dev-alpha-candidate-selection.js";
+import { readGitHubNextDevelopmentVersionReservation } from "../packages/core/next-development-candidate-reservation.js";
 
 export { reconcileActiveReleaseTrain, selectLatestQualifiedSource };
 
@@ -617,6 +618,7 @@ export async function runDevAlphaCandidatePatrol(
     comparison,
     workflowEvidence,
     skippedNewerCommitCount,
+    versionReservation,
     qualificationError,
   } = await resolvePatrolSourceInputs({
     client,
@@ -646,6 +648,7 @@ export async function runDevAlphaCandidatePatrol(
           observedSourceHeadSha,
           skippedNewerCommitCount,
           ...(targetBaseline ? { targetBaseline } : {}),
+          ...(versionReservation ? { versionReservation } : {}),
         },
         workflowEvidence,
         requiredWorkflowPaths,
@@ -992,6 +995,20 @@ export function createGitHubChannelCandidateClient({
         targetBranch,
         parseCandidate: managedCandidateFromPullRequest,
       }),
+    async readNextDevelopmentVersionReservation({
+      reservationSha,
+      candidateSha,
+      targetVersion,
+    }) {
+      return readGitHubNextDevelopmentVersionReservation({
+        api,
+        owner,
+        repo,
+        reservationSha,
+        candidateSha,
+        targetVersion,
+      });
+    },
     async listCompletedWorkflowRuns(workflowPathValue, sourceBranch) {
       const runs = [];
       for (let page = 1; page <= 10; page += 1) {
@@ -1015,7 +1032,11 @@ export function createGitHubChannelCandidateClient({
         for (const commit of rows) {
           const commitSha = text(commit.sha);
           if (commitSha === targetSha) return commits;
-          commits.push(commitSha);
+          commits.push({
+            sha: commitSha,
+            message: text(commit.commit?.message),
+            parents: (commit.parents || []).map((parent) => text(parent.sha)),
+          });
         }
         if (rows.length < 100) return commits;
       }

package/scripts/generate-next-development-guidance.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { nextDevelopmentManual } from "../packages/core/next-development-projection.js";
+
+export const NEXT_DEVELOPMENT_MANUAL_PATH =
+  "docs/next-development-transition.md";
+
+export function generateNextDevelopmentGuidance({
+  cwd = process.cwd(),
+  check = false,
+} = {}) {
+  const target = path.resolve(cwd, NEXT_DEVELOPMENT_MANUAL_PATH);
+  const expected = nextDevelopmentManual();
+  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (check) {
+    if (current !== expected) {
+      throw new Error(
+        `${NEXT_DEVELOPMENT_MANUAL_PATH} drifted from its contract source`,
+      );
+    }
+    return { ok: true, changed: false, path: NEXT_DEVELOPMENT_MANUAL_PATH };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (current !== expected) fs.writeFileSync(target, expected);
+  return {
+    ok: true,
+    changed: current !== expected,
+    path: NEXT_DEVELOPMENT_MANUAL_PATH,
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = generateNextDevelopmentGuidance({
+      check: process.argv.includes("--check"),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`next-development guidance: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/generate-site-bundle.mjs

@@ -50,6 +50,10 @@ const DEV_DELIVERY_AUTHORITY_SCHEMA =
   "schemas/dev-delivery-authority-v2.schema.json";
 const DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE =
   "contracts/dev-delivery-authority-v2.schema.json";
+const V4_COMPATIBILITY_FACTS_SCHEMA =
+  "schemas/v4-compatibility-facts-v1.schema.json";
+const V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE =
+  "contracts/v4-compatibility-facts-v1.schema.json";
 const root = path.resolve(import.meta.dirname, "..");
 const outputDir = path.join(root, "dist", "site");
 const requireFromHere = createRequire(import.meta.url);
@@ -78,9 +82,9 @@ function stableJson(value) {
 }
 
 function siteFileBytes(name, value) {
-  return name === DEV_DELIVERY_AUTHORITY_SCHEMA
-    ? readText(DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE)
-    : stableJson(value);
+  if (name === DEV_DELIVERY_AUTHORITY_SCHEMA) return readText(DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE);
+  if (name === V4_COMPATIBILITY_FACTS_SCHEMA) return readText(V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE);
+  return stableJson(value);
 }
 
 function writeSiteFile(name, value) {
@@ -383,10 +387,12 @@ const manualMetaById = new Map(Object.entries({
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "release-train": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 132 },
+  "next-development-transition": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 133 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
   "v4-canonical-contracts": { capabilityGroup: "governance-versioning", audience: ["developer", "maintainer", "agent"], maturity: "preview", order: 138 },
+  "v4-compatibility-facts": { capabilityGroup: "governance-versioning", audience: ["developer", "maintainer", "agent"], maturity: "preview", order: 139 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "engineering-housekeeper": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer", "agent"], maturity: "preview", order: 145 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
@@ -753,6 +759,7 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/release-train.md",
+      "docs/next-development-transition.md",
       "docs/stable-candidate-patrol.md",
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",
@@ -948,6 +955,7 @@ function buildSiteBundle() {
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/v4-compatibility-facts-v1.schema.json",
       "kfd-support.json",
       "artifact-evidence.json",
       "product-mechanism.json",
@@ -983,6 +991,7 @@ function buildSiteBundle() {
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/v4-compatibility-facts-v1.schema.json",
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1114,6 +1123,7 @@ function buildSiteBundle() {
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/v4-compatibility-facts-v1.schema.json",
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1291,6 +1301,9 @@ function buildSiteBundle() {
     [DEV_DELIVERY_AUTHORITY_SCHEMA]: readJson(
       DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE,
     ),
+    [V4_COMPATIBILITY_FACTS_SCHEMA]: readJson(
+      V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE,
+    ),
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),

package/scripts/init-repo.mjs

@@ -4,6 +4,11 @@ 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";
+import {
+  appendNextDevelopmentToml,
+  mergeNextDevelopmentAgentInstructions,
+  nextDevelopmentWorkflowHeader,
+} from "../packages/core/next-development-projection.js";
 
 const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v4";
 const DEFAULT_PUBLICATION_LATEX_IMAGE = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
@@ -327,7 +332,7 @@ function workflowArtifactPaths(type) {
 }
 
 function publicationWorkflowYaml() {
-  return `# Commit both .buildchain/contract-lock.json and .buildchain/alpha-contract-lock.json.
+  return `${nextDevelopmentWorkflowHeader()}# Commit both .buildchain/contract-lock.json and .buildchain/alpha-contract-lock.json.
 # Persist only @v4 or @v4-alpha; pass temporary train/SHA runtimes through workflow_dispatch.
 name: Build
 
@@ -361,7 +366,7 @@ jobs:
 }
 
 function workflowYaml({ type, runnerPreset, artifactName }) {
-  return `# Buildchain v4 lifecycle checkpoints are governed by architecture/v4-platform-stage-checkpoints.json.
+  return `${nextDevelopmentWorkflowHeader()}# Buildchain v4 lifecycle checkpoints are governed by architecture/v4-platform-stage-checkpoints.json.
 # Do not add undeclared runner-only inputs, outputs, environment, or provider effects.
 # Commit both .buildchain/contract-lock.json and .buildchain/alpha-contract-lock.json.
 # Persist only @v4 or @v4-alpha; pass temporary train/SHA runtimes through workflow_dispatch.
@@ -407,6 +412,13 @@ function writeIfAllowed(filePath, content, { force }) {
   return filePath;
 }
 
+function writeManagedAgentEntry(filePath, current) {
+  const content = mergeNextDevelopmentAgentInstructions(current);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return filePath;
+}
+
 export function initBuildchainRepo({
   cwd = process.cwd(),
   type = "package",
@@ -417,7 +429,7 @@ export function initBuildchainRepo({
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const manager = detectOrDefaultPackageManager(resolvedCwd, packageManager);
-  const toml = (() => {
+  const toml = appendNextDevelopmentToml((() => {
     if (type === "package") {
       return packageToml(resolvedCwd, manager);
     }
@@ -437,7 +449,12 @@ export function initBuildchainRepo({
       return anchoredPackageToml(resolvedCwd, manager);
     }
     throw new Error("init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package");
-  })();
+  })());
+
+  const agentsPath = path.join(resolvedCwd, "AGENTS.md");
+  const currentAgents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, "utf8")
+    : "";
 
   const written = [
     writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
@@ -452,6 +469,7 @@ export function initBuildchainRepo({
           }),
       { force },
     ),
+    writeManagedAgentEntry(agentsPath, currentAgents),
   ];
 
   if (type === "anchored-package" && !fs.existsSync(path.join(resolvedCwd, "release.json"))) {