@kungfu-tech/buildchain 3.0.9-alpha.2 → 3.0.9-alpha.3

package/packages/core/paper-agent-entry.js

@@ -13,6 +13,7 @@ import {
   workCheck,
 } from "./paper-repository.js";
 import { mergePublicationRehearsalAgentInstructions } from "./publication-rehearsal-projection.js";
+import { mergeNextDevelopmentAgentInstructions } from "./next-development-projection.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -168,10 +169,12 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergePublicationRehearsalAgentInstructions(
-        mergePaperAgentEntryInstructions(currentAgents, {
-          developmentRef: resolvedDevelopmentRef,
-        }),
+      mergeNextDevelopmentAgentInstructions(
+        mergePublicationRehearsalAgentInstructions(
+          mergePaperAgentEntryInstructions(currentAgents, {
+            developmentRef: resolvedDevelopmentRef,
+          }),
+        ),
       ),
     ],
   ]);

package/packages/core/paper.js

@@ -51,6 +51,11 @@ import {
   projectPublicationRehearsalToml,
   publicationRehearsalWorkflow,
 } from "./publication-rehearsal-projection.js";
+import {
+  appendNextDevelopmentToml,
+  nextDevelopmentWorkflowHeader,
+  projectNextDevelopmentToml,
+} from "./next-development-projection.js";
 
 export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
 export {
@@ -356,7 +361,7 @@ immutable_base_url = ${tomlString(joinUrl(siteBaseUrl, "archive").replace(/\/$/,
 registry_path = ".buildchain/publication/publication-registry.json"
 `
     : "";
-  return appendPublicationRehearsalToml(`schema = 1
+  return appendNextDevelopmentToml(appendPublicationRehearsalToml(`schema = 1
 
 [project]
 type = "publication-artifact"
@@ -390,14 +395,14 @@ command = "make pdf"
 
 [lifecycle.verify]
 command = "make check"
-`);
+`));
 }
 
 function scaffoldBuildWorkflow(
   buildchainSha,
   { artifactName = "paper-publication" } = {},
 ) {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -425,7 +430,7 @@ jobs:
 }
 
 function scaffoldVerifyWorkflow(buildchainSha) {
-  return `name: Verify
+  return `${nextDevelopmentWorkflowHeader()}name: Verify
 
 on:
   pull_request:
@@ -456,7 +461,7 @@ function scaffoldReleaseWorkflow(
   const passportInput = releasePassportProductName
     ? `      release-passport-product-name: ${JSON.stringify(releasePassportProductName)}\n`
     : "";
-  return `name: Paper Release
+  return `${nextDevelopmentWorkflowHeader()}name: Paper Release
 
 on:
   workflow_dispatch:
@@ -1017,8 +1022,10 @@ function migrationFiles({
   const files = new Map([
     [
       PAPER_PATHS.config,
-      projectPublicationRehearsalToml(
-        fs.readFileSync(path.resolve(cwd, PAPER_PATHS.config), "utf8"),
+      projectNextDevelopmentToml(
+        projectPublicationRehearsalToml(
+          fs.readFileSync(path.resolve(cwd, PAPER_PATHS.config), "utf8"),
+        ),
       ),
     ],
     [PAPER_PATHS.contractLock, contractLockText],

package/scripts/aws-macos-jit-controller-core.mjs

@@ -203,6 +203,87 @@ export function createMacosJitCampaignPlan(values = {}) {
   return { ...plan, digest: digest(plan) };
 }
 
+export function createMacosJitInstanceRehydratePlan(values = {}) {
+  const id = campaignId(values.campaignId);
+  const boundSource = source(values);
+  const aws = commonAws(values);
+  const regionConfig = macosJitRegionConfig(aws.region);
+  const tags = ownershipTags({ id, sourceSha: boundSource.sha });
+  const rehydrationId = exact(
+    values.rehydrationId,
+    /^r[1-9]\d{0,2}$/,
+    "rehydrationId",
+  );
+  const instanceClientToken = `kungfu-mac-rehydrate-${id}-${rehydrationId}`;
+  if (instanceClientToken.length > 64) {
+    throw new Error("rehydration client token exceeds the EC2 limit");
+  }
+  const plan = {
+    schemaVersion: 1,
+    contract: AWS_MACOS_JIT_CONTROLLER_CONTRACT,
+    kind: "instance-rehydrate-plan",
+    repository: repository(values.repository),
+    account: {
+      id: exact(values.accountId, /^\d{12}$/, "accountId"),
+    },
+    github: {
+      workflowId: MACOS_EC2_JIT.workflowId,
+      requiredState: "disabled_manually",
+    },
+    campaign: { id },
+    source: boundSource,
+    aws: {
+      ...aws,
+      hostId: exact(values.hostId, /^h-[0-9a-f]+$/, "hostId"),
+      hostAllocatedAt: iso(values.hostAllocatedAt, "hostAllocatedAt"),
+      replacesInstanceId: exact(
+        values.replacesInstanceId,
+        /^i-[0-9a-f]+$/,
+        "replacesInstanceId",
+      ),
+      rehydrationId,
+      instanceTags: tags,
+      volumeTags: tags,
+      instanceClientToken,
+      rootVolume: {
+        deviceName: "/dev/sda1",
+        deleteOnTermination: true,
+        encrypted: true,
+        volumeSizeGiB: 200,
+        volumeType: "gp3",
+      },
+      metadata: {
+        httpEndpoint: "enabled",
+        httpTokens: "required",
+        httpPutResponseHopLimit: 1,
+        instanceMetadataTags: "disabled",
+      },
+    },
+    safety: {
+      applyMode: values.execute === true ? "execute" : "dry-run",
+      exactSourceRequired: true,
+      existingCampaignHostRequired: true,
+      noHostAllocation: true,
+      zeroActiveInstanceRequired: true,
+      zeroRunnerResidueRequired: true,
+      awsDryRunRequiredBeforeLaunch: true,
+      cleanupOwner: "scheduled-card-scoped-reaper",
+      budget: {
+        name: regionConfig.budgetName,
+        limitUsd: MACOS_EC2_JIT.budgetLimitUsd,
+        metrics: ["UnblendedCost"],
+        dimensionFilter: {
+          usageTypes: regionConfig.budgetUsageTypes,
+          operation: MACOS_EC2_JIT.budgetOperation,
+          regions: regionConfig.budgetRegions,
+        },
+        requiredActualThresholds: [80, 95],
+      },
+    },
+  };
+  return { ...plan, digest: digest(plan) };
+}
+
 export function createMacosJitSourceRebindPlan(values = {}) {
   const id = campaignId(values.campaignId);
   const boundSource = source(values);
@@ -301,9 +382,9 @@ export function macosAllocateHostsArgs(plan) {
 export function macosRunInstancesArgs(plan, { hostId, dryRun = false } = {}) {
   if (
     plan?.contract !== AWS_MACOS_JIT_CONTROLLER_CONTRACT ||
-    plan.kind !== "campaign-launch-plan"
+    !["campaign-launch-plan", "instance-rehydrate-plan"].includes(plan.kind)
   ) {
-    throw new Error("macOS JIT campaign launch plan contract is invalid");
+    throw new Error("macOS JIT instance launch plan contract is invalid");
   }
   const resolvedHostId = exact(hostId, /^h-[0-9a-f]+$/, "hostId");
   const args = [

package/scripts/aws-macos-jit-controller.mjs

@@ -6,6 +6,7 @@ import {
   AWS_MACOS_JIT_CONTROLLER_CONTRACT,
   createMacosJitCampaignPlan,
   createMacosJitClosePlan,
+  createMacosJitInstanceRehydratePlan,
   createMacosJitJobPlan,
   createMacosJitSourceRebindPlan,
   macosAllocateHostsArgs,
@@ -13,6 +14,7 @@ import {
   macosRunInstancesArgs,
 } from "./aws-macos-jit-controller-core.mjs";
 import { MACOS_EC2_JIT_REGIONS } from "./aws-macos-jit-core.mjs";
+import { executeMacosJitInstanceRehydrate } from "./aws-macos-jit-instance-rehydrate.mjs";
 import { executeMacosJitJob } from "./aws-macos-jit-job-controller.mjs";
 import { executeMacosJitSourceRebind } from "./aws-macos-jit-source-rebind.mjs";
 import {
@@ -516,6 +518,19 @@ function confirm(plan) {
       throw new Error("--confirm-zero-allocation is required");
     }
   }
+  if (plan.kind === "instance-rehydrate-plan") {
+    if (arg("confirm-host-id") !== plan.aws.hostId) {
+      throw new Error("--confirm-host-id must equal the exact host id");
+    }
+    if (arg("confirm-replaces-instance-id") !== plan.aws.replacesInstanceId) {
+      throw new Error(
+        "--confirm-replaces-instance-id must equal replacesInstanceId",
+      );
+    }
+    if (!flag("confirm-no-host-allocation")) {
+      throw new Error("--confirm-no-host-allocation is required");
+    }
+  }
 }
 
 function emit(plan, mode, execute, operation) {
@@ -541,6 +556,20 @@ export function main() {
       executeMacosJitCampaignLaunch(plan, { profile: arg("aws-profile") }),
     );
   }
+  if (["plan-rehydrate", "rehydrate-instance"].includes(mode)) {
+    const plan = createMacosJitInstanceRehydratePlan({
+      ...commonValues(execute),
+      hostId: arg("host-id"),
+      hostAllocatedAt: arg("host-allocated-at"),
+      replacesInstanceId: arg("replaces-instance-id"),
+      rehydrationId: arg("rehydration-id"),
+    });
+    return emit(plan, mode, execute, () =>
+      executeMacosJitInstanceRehydrate(plan, {
+        profile: arg("aws-profile"),
+      }),
+    );
+  }
   if (["plan-rebind", "rebind-campaign"].includes(mode)) {
     const plan = createMacosJitSourceRebindPlan({
       ...commonValues(execute),
@@ -550,7 +579,9 @@ export function main() {
       hostId: arg("host-id"),
       instanceId: arg("instance-id"),
     });
-    return emit(plan, mode, execute, () => executeMacosJitSourceRebind(plan, { profile: arg("aws-profile") }));
+    return emit(plan, mode, execute, () =>
+      executeMacosJitSourceRebind(plan, { profile: arg("aws-profile") }),
+    );
   }
   if (["plan-job", "run-job"].includes(mode)) {
     const plan = createMacosJitJobPlan({

package/scripts/aws-macos-jit-instance-rehydrate.mjs

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  AWS_MACOS_JIT_CONTROLLER_CONTRACT,
+  macosRunInstancesArgs,
+} from "./aws-macos-jit-controller-core.mjs";
+import { MACOS_EC2_JIT_REGIONS } from "./aws-macos-jit-core.mjs";
+import {
+  assertDryRun,
+  assertMacosBudgetLaunchGate,
+  assertOwnership,
+  awsArgs,
+  awsJson,
+  commandResult,
+  ghJson,
+  requireSuccess,
+} from "./aws-macos-jit-controller-runtime.mjs";
+
+function assertInstanceRehydratePreflight(plan, profile) {
+  const launchGate = assertMacosBudgetLaunchGate(plan, profile);
+  const commit = ghJson(
+    ["api", `repos/${plan.repository}/commits/${plan.source.sha}`],
+    undefined,
+    "GitHub exact-source preflight",
+  );
+  if (String(commit.sha || "").toLowerCase() !== plan.source.sha) {
+    throw new Error("GitHub did not resolve the exact campaign source SHA");
+  }
+  const host = awsJson(
+    plan,
+    profile,
+    [
+      "ec2",
+      "describe-hosts",
+      "--host-ids",
+      plan.aws.hostId,
+      "--output",
+      "json",
+    ],
+    "macOS rehydration host preflight",
+  ).Hosts?.[0];
+  if (
+    !host ||
+    host.State !== "available" ||
+    host.AvailabilityZone !== plan.aws.availabilityZone ||
+    host.HostProperties?.InstanceType !== plan.aws.instanceType ||
+    (host.Instances || []).length !== 0 ||
+    new Date(host.AllocationTime).toISOString() !== plan.aws.hostAllocatedAt
+  ) {
+    throw new Error("macOS rehydration host identity or capacity mismatch");
+  }
+  assertOwnership(host.Tags, plan);
+
+  const regionalPlans = Object.keys(MACOS_EC2_JIT_REGIONS).map((region) => ({
+    ...plan,
+    aws: { ...plan.aws, region },
+  }));
+  const otherHosts = regionalPlans.flatMap((regionalPlan) =>
+    (
+      awsJson(
+        regionalPlan,
+        profile,
+        [
+          "ec2",
+          "describe-hosts",
+          "--filter",
+          "Name=tag:kungfu:plane,Values=aws-us-elastic-runner-burst",
+          "Name=tag:kungfu:provider,Values=macos-ec2-jit",
+          "Name=state,Values=available,pending,under-assessment",
+          "--output",
+          "json",
+        ],
+        `macOS rehydration host ceiling in ${regionalPlan.aws.region}`,
+      ).Hosts || []
+    ).filter((candidate) => candidate.HostId !== plan.aws.hostId),
+  );
+  if (otherHosts.length !== 0) {
+    throw new Error("macOS rehydration found another active Dedicated Host");
+  }
+  const activeInstances = regionalPlans.flatMap((regionalPlan) => {
+    const active = awsJson(
+      regionalPlan,
+      profile,
+      [
+        "ec2",
+        "describe-instances",
+        "--filters",
+        "Name=tag:kungfu:plane,Values=aws-us-elastic-runner-burst",
+        "Name=tag:kungfu:provider,Values=macos-ec2-jit",
+        "Name=instance-state-name,Values=pending,running,stopping,stopped,shutting-down",
+        "--output",
+        "json",
+      ],
+      `active macOS JIT instance preflight in ${regionalPlan.aws.region}`,
+    );
+    return (active.Reservations || []).flatMap(
+      (reservation) => reservation.Instances || [],
+    );
+  });
+  if (activeInstances.length !== 0) {
+    throw new Error("macOS rehydration requires zero active JIT instances");
+  }
+  const runners = ghJson(
+    ["api", `repos/${plan.repository}/actions/runners?per_page=100`],
+    undefined,
+    "macOS rehydration runner preflight",
+  ).runners;
+  if (
+    (runners || []).some((runner) =>
+      (runner.labels || []).some((label) =>
+        String(label.name || label).startsWith("aws-us-ec2-macos-jit-"),
+      ),
+    )
+  ) {
+    throw new Error("macOS rehydration requires zero JIT runner residue");
+  }
+  const image = awsJson(
+    plan,
+    profile,
+    [
+      "ec2",
+      "describe-images",
+      "--image-ids",
+      plan.aws.amiId,
+      "--output",
+      "json",
+    ],
+    "macOS rehydration AMI preflight",
+  ).Images?.[0];
+  if (
+    !image ||
+    image.Name !== plan.aws.amiName ||
+    image.Architecture !== "arm64_mac" ||
+    image.State !== "available"
+  ) {
+    throw new Error("macOS AMI identity or availability mismatch");
+  }
+  const subnet = awsJson(
+    plan,
+    profile,
+    [
+      "ec2",
+      "describe-subnets",
+      "--subnet-ids",
+      plan.aws.subnetId,
+      "--output",
+      "json",
+    ],
+    "macOS rehydration subnet preflight",
+  ).Subnets?.[0];
+  if (!subnet || subnet.AvailabilityZone !== plan.aws.availabilityZone) {
+    throw new Error(
+      "macOS subnet and Dedicated Host availability zone mismatch",
+    );
+  }
+  return {
+    ...launchGate,
+    exactCommit: plan.source.sha,
+    hostId: host.HostId,
+    hostState: host.State,
+    activeInstances: 0,
+    otherActiveHosts: 0,
+    amiOwnerId: image.OwnerId,
+    subnetAvailabilityZone: subnet.AvailabilityZone,
+  };
+}
+
+export function executeMacosJitInstanceRehydrate(plan, { profile = "" } = {}) {
+  if (
+    plan?.contract !== AWS_MACOS_JIT_CONTROLLER_CONTRACT ||
+    plan.kind !== "instance-rehydrate-plan"
+  ) {
+    throw new Error("macOS JIT instance rehydrate plan contract is invalid");
+  }
+  const preflight = assertInstanceRehydratePreflight(plan, profile);
+  assertDryRun(
+    commandResult(
+      "aws",
+      awsArgs(
+        plan,
+        profile,
+        macosRunInstancesArgs(plan, { hostId: plan.aws.hostId, dryRun: true }),
+      ),
+    ),
+    "EC2 same-host RunInstances DryRun",
+  );
+  const launched = awsJson(
+    plan,
+    profile,
+    macosRunInstancesArgs(plan, { hostId: plan.aws.hostId }),
+    "EC2 same-host RunInstances",
+  );
+  const instanceId = launched.Instances?.[0]?.InstanceId;
+  if (!/^i-[0-9a-f]+$/.test(String(instanceId || ""))) {
+    throw new Error("EC2 same-host RunInstances returned no instance identity");
+  }
+  requireSuccess(
+    commandResult(
+      "aws",
+      awsArgs(plan, profile, [
+        "ec2",
+        "wait",
+        "instance-running",
+        "--instance-ids",
+        instanceId,
+      ]),
+    ),
+    "macOS rehydrated instance-running waiter",
+  );
+  const instance = awsJson(
+    plan,
+    profile,
+    [
+      "ec2",
+      "describe-instances",
+      "--instance-ids",
+      instanceId,
+      "--output",
+      "json",
+    ],
+    "macOS rehydrated instance readback",
+  ).Reservations?.[0]?.Instances?.[0];
+  if (
+    !instance ||
+    instance.State?.Name !== "running" ||
+    instance.Placement?.HostId !== plan.aws.hostId ||
+    instance.ImageId !== plan.aws.amiId ||
+    instance.InstanceType !== plan.aws.instanceType
+  ) {
+    throw new Error("macOS rehydrated instance identity or placement mismatch");
+  }
+  assertOwnership(instance.Tags, plan);
+  return {
+    schemaVersion: 1,
+    contract: AWS_MACOS_JIT_CONTROLLER_CONTRACT,
+    kind: "instance-rehydrate-result",
+    status: "rehydrated",
+    repository: plan.repository,
+    campaign: plan.campaign,
+    source: plan.source,
+    replacement: {
+      rehydrationId: plan.aws.rehydrationId,
+      replacesInstanceId: plan.aws.replacesInstanceId,
+    },
+    aws: {
+      region: plan.aws.region,
+      availabilityZone: plan.aws.availabilityZone,
+      hostId: plan.aws.hostId,
+      hostAllocatedAt: plan.aws.hostAllocatedAt,
+      instanceId,
+      instanceType: instance.InstanceType,
+      imageId: instance.ImageId,
+      launchTime: new Date(instance.LaunchTime).toISOString(),
+    },
+    preflight,
+    dryRun: "RunInstances:DryRunOperation",
+    hostAllocated: false,
+    planDigest: plan.digest,
+  };
+}

package/scripts/check-inventory.mjs

@@ -53,6 +53,10 @@ const requiredPaths = [
   "packages/core/homebrew.js",
   "packages/core/artifact-verification-envelope.js",
   "packages/core/anchored-version-material.js",
+  "packages/core/next-development-transition.js",
+  "packages/core/next-development-controller.js",
+  "packages/core/next-development-candidate-reservation.js",
+  "packages/core/next-development-projection.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
   "packages/core/publication-reproducibility.js",
@@ -75,6 +79,8 @@ const requiredPaths = [
   "docs/auditable-demo.md",
   "contracts/auditable-demo-scenario-v1.schema.json",
   "contracts/release-candidate-recovery-v1.schema.json",
+  "contracts/next-development-request-v1.schema.json",
+  "contracts/next-development-transition-v1.schema.json",
   "contracts/auditable-demo-media-profiles-v1.json",
   "contracts/evidence/auditable-demo-web-delivery-v1.json",
   "contracts/evidence/auditable-demo-responsive-web-delivery-v1.json",
@@ -86,10 +92,15 @@ const requiredPaths = [
   "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/public-projection.json",
   "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/scene.json",
   "docs/release-propagation.md",
+  "docs/next-development-transition.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",
   "docs/versioning.md",
   "scripts/release-line-dry-run.mjs",
+  "scripts/next-development-transition.mjs",
+  "scripts/next-development-self-dogfood.mjs",
+  "scripts/next-development-self-dogfood-harness.mjs",
+  "scripts/generate-next-development-guidance.mjs",
   "scripts/reconcile-release-governance.mjs",
   "scripts/buildchain-channel-router.mjs",
   "scripts/generate-channel-build-workflow.mjs",

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

@@ -368,6 +368,7 @@ 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 },
@@ -733,6 +734,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",