@kungfu-tech/buildchain 3.0.1 → 3.0.2-alpha.1

package/scripts/generate-site-bundle.mjs

@@ -15,6 +15,10 @@ import {
   collectKfdUpstreamFacts,
 } from "../packages/core/kfd.js";
 import { KFD_AGENT_HUB_ADOPTION_SCHEMA } from "../packages/core/kfd-agent-hub.js";
+import {
+  KFD_PRODUCT_GATE_INPUT_SCHEMA,
+  KFD_SUPPORT_PROJECTION_SCHEMA,
+} from "../packages/core/kfd-product-gates.js";
 import {
   createReadmeBadgeEndpointRegistry,
 } from "../packages/core/readme-badges.js";
@@ -445,6 +449,15 @@ function cliCommandMeta(id) {
     "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." },
+    "kfd-4-gate": { group: "kfd-trust", purpose: "Evaluate source-bound KFD-4 observer-perspective and contrastive-replay product evidence." },
+    "kfd-4-verify": { group: "kfd-trust", purpose: "Verify a retained KFD-4 product-gate result without widening product support." },
+    "kfd-5-schema": { group: "kfd-trust", purpose: "Print the default KFD-5 schema exposed by the KFD package standards metadata." },
+    "kfd-5-gate": { group: "kfd-trust", purpose: "Evaluate source-bound KFD-5 Primitive discovery qualification evidence." },
+    "kfd-5-verify": { group: "kfd-trust", purpose: "Verify a retained KFD-5 product-gate result without widening product support." },
+    "kfd-7-schema": { group: "kfd-trust", purpose: "Print the default KFD-7 schema exposed by the KFD package standards metadata." },
+    "kfd-7-gate": { group: "kfd-trust", purpose: "Evaluate a source-bound KFD-7 Domain Profile, evidence obligations, and independent review." },
+    "kfd-7-verify": { group: "kfd-trust", purpose: "Verify a retained KFD-7 product-gate result without widening product support." },
+    "kfd-support": { group: "kfd-trust", purpose: "Project and verify a product-owned KFD-1 through KFD-13 support matrix against KFD-4/5/7 gates." },
     "kfd-aggregate": { group: "kfd-trust", purpose: "Return a product KFD view that combines own KFD status with upstream KFD aggregate facts." },
     "kfd-upstream": { group: "kfd-trust", purpose: "Inspect KFD upstream aggregate command families." },
     "kfd-upstream-check": { group: "kfd-trust", purpose: "Validate a KFD upstream aggregate document and fail closed on missing evidence." },
@@ -503,6 +516,7 @@ function nodeApiMeta(exportName) {
     "./homebrew": { group: "distribution-indexes", summary: "Homebrew tap fact collection, Formula rendering, update, and check APIs." },
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
+    "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
     "./portable-dev-cache": { group: "observability-diagnostics", summary: "Portable dependency/compiler cache plan, exact-root verification, and provider receipt APIs." },
@@ -529,6 +543,7 @@ function nodeApiMeta(exportName) {
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },
     "./buildchain-layout": { group: "kfd-trust", summary: "Versioned Buildchain repository-layout discovery contract plus canonical .buildchain 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, upstream KFD aggregate facts, and Buildchain KFD claim helpers." },
+    "./kfd-product-gates": { group: "kfd-trust", summary: "Fail-closed KFD-4, KFD-5, and KFD-7 product evidence gates plus non-widening KFD support-matrix release projections." },
     "./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." },
@@ -993,6 +1008,9 @@ function buildSiteBundle() {
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
+      "schemas/kfd-product-gate-input-v1.schema.json",
+      "schemas/kfd-support-projection-v1.schema.json",
+      "kfd-support.json",
       "artifact-evidence.json",
       "product-mechanism.json",
       "impact.json",
@@ -1021,6 +1039,8 @@ function buildSiteBundle() {
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
+      "schemas/kfd-product-gate-input-v1.schema.json",
+      "schemas/kfd-support-projection-v1.schema.json",
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1150,6 +1170,8 @@ function buildSiteBundle() {
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
+      "schemas/kfd-product-gate-input-v1.schema.json",
+      "schemas/kfd-support-projection-v1.schema.json",
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1323,6 +1345,8 @@ function buildSiteBundle() {
     "release-passport-check-manifest.json": createReleasePassportCheckManifest(),
     "schemas/release-passport-v1.schema.json": RELEASE_PASSPORT_SCHEMA,
     "schemas/kfd-agent-hub-adoption.schema.json": KFD_AGENT_HUB_ADOPTION_SCHEMA,
+    "schemas/kfd-product-gate-input-v1.schema.json": KFD_PRODUCT_GATE_INPUT_SCHEMA,
+    "schemas/kfd-support-projection-v1.schema.json": KFD_SUPPORT_PROJECTION_SCHEMA,
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),

package/scripts/locked-source-checkout.mjs

@@ -177,6 +177,21 @@ function gitObjectDirectory(referencePath) {
   return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) || "";
 }
 
+function directoryBytes(directory) {
+  if (!fs.existsSync(directory)) return 0;
+  let bytes = 0;
+  const pending = [directory];
+  while (pending.length) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const child = path.join(current, entry.name);
+      if (entry.isDirectory()) pending.push(child);
+      else if (entry.isFile()) bytes += fs.statSync(child).size;
+    }
+  }
+  return bytes;
+}
+
 function writeAlternates(targetPath, referencePath) {
   const objectDirectory = gitObjectDirectory(referencePath);
   if (!objectDirectory) {
@@ -413,6 +428,13 @@ export function lockedSourceCheckout({
       fallbackUsed: normalizedMode === "off",
       fallbackReason: normalizedMode === "off" ? "cache disabled" : "",
       githubFetchAttempts: 0,
+      lookupDurationMs: 0,
+      restoreDurationMs: 0,
+      githubFetchDurationMs: 0,
+      restoredBytes: null,
+      restoredBytesStatus:
+        normalizedMode === "off" ? "not-applicable" : "unavailable",
+      restoredBytesMethod: "",
     },
     verification: {
       head: "",
@@ -425,8 +447,13 @@ export function lockedSourceCheckout({
   let checkoutError;
   let checkoutSha = sha;
   if (normalizedMode !== "off") {
+    const cacheAttemptStartedAt = Date.now();
+    const objectBytesBefore = directoryBytes(
+      path.join(targetPath, ".git", "objects"),
+    );
     try {
       if (renderedReferenceRepository) {
+        const lookupStartedAt = Date.now();
         const alternates = writeAlternates(targetPath, renderedReferenceRepository);
         evidence.cache.transport = "reference-repository";
         evidence.cache.referenceAvailable = alternates;
@@ -436,9 +463,13 @@ export function lockedSourceCheckout({
         if (!hasCommit(targetPath, sha, timeoutMs)) {
           throw new Error("reference repository does not contain source commit");
         }
+        evidence.cache.lookupDurationMs = Date.now() - lookupStartedAt;
+        const restoreStartedAt = Date.now();
         checkoutFetchedCommit(targetPath, sha, timeoutMs);
+        evidence.cache.restoreDurationMs = Date.now() - restoreStartedAt;
       } else if (renderedMirrorUrl) {
         evidence.cache.transport = "mirror-url";
+        const restoreStartedAt = Date.now();
         const fetchResult = fetchSourceCommit({
           targetPath,
           remoteName: "buildchain-cache",
@@ -452,15 +483,29 @@ export function lockedSourceCheckout({
         evidence.cache.fetchMode = fetchResult.fetchMode;
         checkoutSha = fetchResult.checkoutSha || sha;
         checkoutFetchedCommit(targetPath, checkoutSha, timeoutMs);
+        evidence.cache.restoreDurationMs = Date.now() - restoreStartedAt;
       } else {
         throw new Error("checkout cache is enabled but no mirror URL or reference repository template was provided");
       }
       evidence.cache.hit = true;
       evidence.cache.fallbackUsed = false;
+      evidence.cache.restoredBytes = Math.max(
+        0,
+        directoryBytes(path.join(targetPath, ".git", "objects")) -
+          objectBytesBefore,
+      );
+      evidence.cache.restoredBytesStatus = "observed";
+      evidence.cache.restoredBytesMethod = "git-object-store-delta";
     } catch (error) {
       checkoutError = error;
       evidence.cache.hit = false;
       evidence.cache.fallbackReason = error.message;
+      if (
+        evidence.cache.lookupDurationMs === 0 &&
+        evidence.cache.restoreDurationMs === 0
+      ) {
+        evidence.cache.lookupDurationMs = Date.now() - cacheAttemptStartedAt;
+      }
       if (normalizedMode === "require" || normalizedFallback === "fail") {
         evidence.durationMs = Date.now() - startedAt;
         writeEvidence(path.resolve(workspace, diagnosticsPath), evidence);
@@ -477,6 +522,7 @@ export function lockedSourceCheckout({
       evidence.cache.fallbackReason = checkoutError.message;
     }
     try {
+      const githubFetchStartedAt = Date.now();
       const fetchResult = runBoundedFetch({
         attempts: normalizedFetchAttempts,
         fetch: () => fetchSourceCommit({
@@ -496,6 +542,8 @@ export function lockedSourceCheckout({
       evidence.cache.githubFetchAttempts = fetchResult.attempts;
       evidence.cache.fetchMode = fetchResult.value.fetchMode;
       checkoutSha = fetchResult.value.checkoutSha || sha;
+      evidence.cache.githubFetchDurationMs =
+        Date.now() - githubFetchStartedAt;
     } catch (error) {
       evidence.durationMs = Date.now() - startedAt;
       writeEvidence(path.resolve(workspace, diagnosticsPath), evidence);

package/scripts/promotion-routing-evidence.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+function createPromotionRoutingEvidence({
+  env = process.env,
+  cwd = process.cwd(),
+} = {}) {
+  const routing = {
+    schemaVersion: 1,
+    contract: "buildchain.promotion-routing/v1",
+    router: { ref: env.ROUTER_REF, sha: env.ROUTER_SHA },
+    shell: {
+      channel: env.SHELL_CHANNEL,
+      ref: env.SHELL_REF,
+      sha: env.SHELL_SHA,
+    },
+    runtime: {
+      requestedRef: env.RUNTIME_REF,
+      resolvedSha: env.RUNTIME_SHA,
+    },
+    contractLock: { path: env.LOCK_PATH, digest: env.LOCK_DIGEST },
+    publication: {
+      channel: env.PUBLICATION_CHANNEL,
+      targetRef: env.TARGET_REF,
+    },
+    trustedOverrideUsed: env.OVERRIDE_USED === "true",
+  };
+  const controllerDir = path.join(cwd, ".buildchain", "controller");
+  const routingPath = path.join(controllerDir, "promotion-routing.json");
+  const candidatePath = path.join(
+    controllerDir,
+    "release-candidate-promotion-passport.json",
+  );
+  const candidate = JSON.parse(
+    fs.readFileSync(path.resolve(cwd, env.RELEASE_CANDIDATE_PASSPORT), "utf8"),
+  );
+  fs.mkdirSync(controllerDir, { recursive: true });
+  fs.writeFileSync(routingPath, `${JSON.stringify(routing, null, 2)}\n`);
+  fs.writeFileSync(
+    candidatePath,
+    `${JSON.stringify({ ...candidate, promotionRouting: routing }, null, 2)}\n`,
+  );
+  if (env.GITHUB_OUTPUT) {
+    fs.appendFileSync(
+      env.GITHUB_OUTPUT,
+      [
+        "routing-path=.buildchain/controller/promotion-routing.json",
+        "candidate-passport-path=.buildchain/controller/release-candidate-promotion-passport.json",
+        "",
+      ].join("\n"),
+    );
+  }
+  return { routing, routingPath, candidatePath };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    createPromotionRoutingEvidence();
+  } catch (error) {
+    console.error(
+      `promotion routing evidence failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+export { createPromotionRoutingEvidence };

package/scripts/reconcile-github-governance.mjs

@@ -90,6 +90,12 @@ function readJson(filePath, label) {
   }
 }
 
+function writeJson(filePath, value) {
+  const target = path.resolve(filePath);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 function githubApi(route, { method = "GET", body } = {}) {
   const args = [
     "api",
@@ -142,6 +148,42 @@ function readRuleset(repository, rulesetId) {
   return normalizeGithubRulesetSnapshot(response.data);
 }
 
+function readMatchingRulesetEntries(repository, branch) {
+  const response = githubApi(
+    `repos/${repository}/rulesets?includes_parents=false&per_page=100`,
+  );
+  const include = `refs/heads/${branch}`;
+  return (response.data || [])
+    .map((entry) => ({
+      id: Number(entry.id),
+      ruleset: readRuleset(repository, entry.id),
+    }))
+    .filter(({ ruleset }) => {
+      const refName = ruleset.conditions?.ref_name || {};
+      return (
+        ruleset.target === "branch" &&
+        (refName.include || []).length === 1 &&
+        refName.include[0] === include &&
+        (refName.exclude || []).length === 0
+      );
+    })
+    .sort((left, right) => left.ruleset.name.localeCompare(right.ruleset.name));
+}
+
+function readMatchingRulesets(repository, branch) {
+  return readMatchingRulesetEntries(repository, branch).map(
+    ({ ruleset }) => ruleset,
+  );
+}
+
+function rulesetInventory(repository, branch) {
+  return {
+    repository,
+    targetRef: branch,
+    matchingRulesets: readMatchingRulesets(repository, branch),
+  };
+}
+
 function snapshotCore(repository, branch, protection) {
   return {
     schemaVersion: 1,
@@ -200,8 +242,8 @@ function rulesetPlan(args) {
     ...planCore,
     planRoot: githubGovernanceDigest(planCore),
   };
-  fs.writeFileSync(path.resolve(snapshotOutput), `${JSON.stringify(snapshot, null, 2)}\n`);
-  fs.writeFileSync(path.resolve(planOutput), `${JSON.stringify(finalPlan, null, 2)}\n`);
+  writeJson(snapshotOutput, snapshot);
+  writeJson(planOutput, finalPlan);
   return finalPlan;
 }
 
@@ -209,13 +251,45 @@ function rulesetPolicyPlan(args) {
   const repository = required(flag(args, "repository"), "--repository");
   const branch = required(flag(args, "branch"), "--branch")
     .replace(/^refs\/heads\//, "");
-  const rulesetId = Number(required(flag(args, "ruleset-id"), "--ruleset-id"));
-  if (!Number.isInteger(rulesetId) || rulesetId <= 0) {
-    throw new Error("--ruleset-id must be a positive integer");
-  }
+  const requestedRulesetId = flag(args, "ruleset-id");
+  const rulesetName = required(flag(args, "ruleset-name"), "--ruleset-name");
   const snapshotOutput = required(flag(args, "snapshot-output"), "--snapshot-output");
   const planOutput = required(flag(args, "plan-output"), "--plan-output");
-  const before = readRuleset(repository, rulesetId);
+  const matchingEntries = readMatchingRulesetEntries(repository, branch);
+  const inventory = {
+    repository,
+    targetRef: branch,
+    matchingRulesets: matchingEntries.map(({ ruleset }) => ruleset),
+  };
+  let rulesetId = null;
+  let before = null;
+  if (requestedRulesetId) {
+    rulesetId = Number(requestedRulesetId);
+    if (!Number.isInteger(rulesetId) || rulesetId <= 0) {
+      throw new Error("--ruleset-id must be a positive integer");
+    }
+    before = readRuleset(repository, rulesetId);
+    if (
+      !inventory.matchingRulesets.some(
+        (ruleset) =>
+          githubGovernanceDigest(ruleset) === githubGovernanceDigest(before),
+      )
+    ) {
+      throw new Error("--ruleset-id does not target the exact requested branch");
+    }
+  } else if (matchingEntries.length === 1) {
+    before = matchingEntries[0].ruleset;
+    rulesetId = matchingEntries[0].id;
+    if (!Number.isInteger(rulesetId) || rulesetId <= 0) {
+      throw new Error("matching ruleset id could not be resolved");
+    }
+  } else if (inventory.matchingRulesets.length > 1) {
+    throw new Error("multiple exact-target rulesets are ambiguous");
+  } else if (!hasFlag(args, "create-if-missing")) {
+    throw new Error(
+      "exact-target ruleset is absent; pass --create-if-missing to plan creation",
+    );
+  }
   const targetPolicy = resolveGithubGovernanceTargetPolicy({
     repository,
     targetRef: branch,
@@ -225,6 +299,7 @@ function rulesetPolicyPlan(args) {
     contract: "kungfu-buildchain-github-governance-ruleset-rollback-snapshot",
     repository,
     targetRef: branch,
+    rulesetExists: Boolean(before),
     rulesetId,
     ruleset: before,
   };
@@ -236,13 +311,16 @@ function rulesetPolicyPlan(args) {
     repository,
     targetRef: branch,
     rulesetId,
-    inventory: before,
+    rulesetName,
+    inventory,
     rollbackSnapshot: before,
     desiredProtection: {
       strictRequiredChecks: targetPolicy.strictRequiredChecks,
       requiredCheckBindings: targetPolicy.requiredCheckBindings,
       requiredApprovals: targetPolicy.requiredApprovals,
       rulesetBypassActors: [],
+      blockDeletions: hasFlag(args, "block-deletions"),
+      blockNonFastForward: hasFlag(args, "block-non-fast-forward"),
     },
   });
   const boundCore = {
@@ -255,8 +333,8 @@ function rulesetPolicyPlan(args) {
     ...planCore,
     planRoot: githubGovernanceDigest(planCore),
   };
-  fs.writeFileSync(path.resolve(snapshotOutput), `${JSON.stringify(snapshot, null, 2)}\n`);
-  fs.writeFileSync(path.resolve(planOutput), `${JSON.stringify(finalPlan, null, 2)}\n`);
+  writeJson(snapshotOutput, snapshot);
+  writeJson(planOutput, finalPlan);
   return finalPlan;
 }
 
@@ -276,20 +354,29 @@ function rulesetApply(args) {
       snapshotRoot !== githubGovernanceDigest(snapshotCore)) {
     throw new Error("ruleset rollback snapshot root mismatch");
   }
-  const current = readRuleset(rollout.repository, rollout.rulesetId);
-  if (githubGovernanceDigest(current) !== rollout.inventoryRoot) {
+  const currentInventory = rulesetInventory(
+    rollout.repository,
+    rollout.targetRef,
+  );
+  if (githubGovernanceDigest(currentInventory) !== rollout.inventoryRoot) {
     throw new Error("live GitHub ruleset drifted after planning; apply stopped");
   }
-  githubApi(rollout.operations[0].endpoint, {
+  const result = githubApi(rollout.operations[0].endpoint, {
     method: rollout.operations[0].method,
     body: rollout.operations[0].body,
   });
-  const after = readRuleset(rollout.repository, rollout.rulesetId);
+  const rulesetId =
+    rollout.rulesetId ||
+    Number(result.data?.id || 0);
+  if (!Number.isInteger(rulesetId) || rulesetId <= 0) {
+    throw new Error("GitHub did not return the created ruleset id");
+  }
+  const after = readRuleset(rollout.repository, rulesetId);
   const afterRoot = githubGovernanceDigest(after);
   if (afterRoot !== rollout.expectedObservation.rulesetRoot) {
     throw new Error("post-change GitHub ruleset read-back does not match the rollout plan");
   }
-  return {
+  const receiptCore = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-github-governance-ruleset-rollout-receipt",
     status: "applied",
@@ -297,7 +384,21 @@ function rulesetApply(args) {
     snapshotRoot: rollout.snapshotRoot,
     afterRoot,
     repository: rollout.repository,
-    rulesetId: rollout.rulesetId,
+    targetRef: rollout.targetRef,
+    rulesetId,
+    rollback:
+      rollout.action === "create"
+        ? {
+            method: "DELETE",
+            endpoint: rulesetEndpoint(rollout.repository, rulesetId),
+            body: null,
+            preconditionRoot: afterRoot,
+          }
+        : rollout.rollback[0],
+  };
+  return {
+    ...receiptCore,
+    receiptRoot: githubGovernanceDigest(receiptCore),
   };
 }
 
@@ -311,14 +412,46 @@ function rulesetRollback(args) {
   if (rollout.snapshotRoot !== confirmed) {
     throw new Error("--confirm-rollback-root does not match the frozen ruleset snapshot");
   }
-  const operation = rollout.rollback[0];
+  let rulesetId = rollout.rulesetId;
+  let operation = rollout.rollback[0];
+  if (operation.requiresApplyReceipt) {
+    const receipt = readJson(
+      required(flag(args, "apply-receipt"), "--apply-receipt"),
+      "ruleset apply receipt",
+    );
+    const { receiptRoot, ...receiptCore } = receipt;
+    if (
+      receiptRoot !== githubGovernanceDigest(receiptCore) ||
+      receipt.planRoot !== rollout.planRoot ||
+      receipt.repository !== rollout.repository ||
+      receipt.targetRef !== rollout.targetRef
+    ) {
+      throw new Error("ruleset apply receipt does not match the rollout plan");
+    }
+    rulesetId = Number(receipt.rulesetId);
+    operation = receipt.rollback;
+    const current = readRuleset(rollout.repository, rulesetId);
+    if (githubGovernanceDigest(current) !== operation.preconditionRoot) {
+      throw new Error("created ruleset drifted after apply; rollback stopped");
+    }
+  }
   githubApi(operation.endpoint, {
     method: operation.method,
     body: operation.body,
   });
-  const restored = readRuleset(rollout.repository, rollout.rulesetId);
-  if (githubGovernanceDigest(restored) !== operation.preconditionRoot) {
-    throw new Error("ruleset rollback read-back does not match the frozen snapshot");
+  if (operation.method === "DELETE") {
+    const remaining = readMatchingRulesets(
+      rollout.repository,
+      rollout.targetRef,
+    );
+    if (remaining.length !== 0) {
+      throw new Error("created ruleset remains after rollback");
+    }
+  } else {
+    const restored = readRuleset(rollout.repository, rulesetId);
+    if (githubGovernanceDigest(restored) !== operation.preconditionRoot) {
+      throw new Error("ruleset rollback read-back does not match the frozen snapshot");
+    }
   }
   return {
     schemaVersion: 1,
@@ -327,7 +460,7 @@ function rulesetRollback(args) {
     planRoot: rollout.planRoot,
     snapshotRoot: rollout.snapshotRoot,
     repository: rollout.repository,
-    rulesetId: rollout.rulesetId,
+    rulesetId,
   };
 }
 
@@ -368,8 +501,8 @@ function protectionPolicyPlan(args) {
     ...boundCore,
     planRoot: githubGovernanceDigest(boundCore),
   };
-  fs.writeFileSync(path.resolve(snapshotOutput), `${JSON.stringify(snapshotWithRoot, null, 2)}\n`);
-  fs.writeFileSync(path.resolve(planOutput), `${JSON.stringify(finalPlan, null, 2)}\n`);
+  writeJson(snapshotOutput, snapshotWithRoot);
+  writeJson(planOutput, finalPlan);
   return finalPlan;
 }
 
@@ -419,8 +552,8 @@ function plan(args) {
     ...boundCore,
     planRoot: githubGovernanceDigest(boundCore),
   };
-  fs.writeFileSync(path.resolve(snapshotOutput), `${JSON.stringify(snapshotWithRoot, null, 2)}\n`);
-  fs.writeFileSync(path.resolve(planOutput), `${JSON.stringify(finalPlan, null, 2)}\n`);
+  writeJson(snapshotOutput, snapshotWithRoot);
+  writeJson(planOutput, finalPlan);
   return finalPlan;
 }
 

package/scripts/shifu-gate-profile.mjs

@@ -114,10 +114,24 @@ export function prepareGateExecutionFiles(files) {
   for (const file of files) fs.rmSync(file, { force: true });
 }
 
+export function commandSpawnOptions({
+  cwd,
+  env = process.env,
+  streamOutput = false,
+} = {}) {
+  if (streamOutput) return { cwd, env, stdio: "inherit" };
+  return {
+    cwd,
+    env,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  };
+}
+
 function runArgv(
   argv,
   args,
-  { cwd, env = process.env, allowFailure = false } = {},
+  { cwd, env = process.env, allowFailure = false, streamOutput = false } = {},
 ) {
   const command = argv[0];
   const commandArgs = [...argv.slice(1), ...args];
@@ -126,25 +140,12 @@ function runArgv(
   const batchInvocation = windowsBatch
     ? windowsBatchInvocation(command, commandArgs, { cwd })
     : null;
+  const spawnOptions = commandSpawnOptions({ cwd, env, streamOutput });
   const result = windowsBatch
-    ? spawnSync(
-        batchInvocation.command,
-        batchInvocation.args,
-        {
-          cwd,
-          env,
-          encoding: "utf8",
-          maxBuffer: 16 * 1024 * 1024,
-        },
-      )
-    : spawnSync(command, commandArgs, {
-        cwd,
-        env,
-        encoding: "utf8",
-        maxBuffer: 16 * 1024 * 1024,
-      });
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
+    ? spawnSync(batchInvocation.command, batchInvocation.args, spawnOptions)
+    : spawnSync(command, commandArgs, spawnOptions);
+  if (!streamOutput && result.stdout) process.stdout.write(result.stdout);
+  if (!streamOutput && result.stderr) process.stderr.write(result.stderr);
   if (result.error) throw result.error;
   const status = result.status ?? 1;
   if (!allowFailure && status !== 0)
@@ -257,7 +258,12 @@ function runMode() {
     ],
     registry,
   );
-  const runResult = runArgv(argv, runArgs, { cwd, env, allowFailure: true });
+  const runResult = runArgv(argv, runArgs, {
+    cwd,
+    env,
+    allowFailure: true,
+    streamOutput: true,
+  });
   let receipt = fs.existsSync(receiptPath)
     ? readJson(receiptPath, "Shifu gate receipt")
     : null;