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

package/docs/cli.md

@@ -276,10 +276,14 @@ platform packages with version, dist-tag, and digest evidence. Verification
 fails closed if supplied sections are internally incomplete or point to
 artifacts without matching evidence.
 
-`--impact-json` supplies the surface-aware impact ledger. When it includes
-`surfaceImpacts[]`, the verifier requires `versionImpact.final` to match the
-highest declared surface impact and copies `versionImpact` plus
-`surfaceImpacts` into `buildchain.release.json`. This lets
+`--impact-json` supplies the surface-aware impact ledger. Production release
+passports (`release/*`) and major publish-gate passports require
+`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it
+optional. When `surfaceImpacts[]` is required or supplied, the verifier requires
+each entry to include an id, impact, and rationale, and requires
+`versionImpact.final` to match the highest declared surface impact. The
+collector copies `versionImpact` plus `surfaceImpacts` into
+`buildchain.release.json`. This lets
 `buildchain explain release --for agent --json` state why a release is patch,
 minor, or major instead of relying on file-path memory.
 

package/docs/release-passport.md

@@ -106,11 +106,15 @@ dist-tag, registry, role, platform, and digest, so agents do not need to stitch
 npm facts back together from the lower-level evidence files.
 `buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the
 build and npm dist-tag evidence chain in the same passport.
-`impact.json` can be supplied with `--impact-json`; when it contains
-`surfaceImpacts[]`, verification fails closed unless `versionImpact.final`
-matches the highest surface impact. For example, KFD-2 content can remain patch
-while an additive `registry.kind` field on the machine-consumed KFD registry
-schema records a minor `kfd-registry-schema` surface impact.
+`impact.json` can be supplied with `--impact-json`. Production release
+passports (`release/*`) and major publish-gate passports require
+`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field
+optional. When `surfaceImpacts[]` is required or supplied, verification fails
+closed unless each entry has an id, impact, and rationale, and
+`versionImpact.final` matches the highest surface impact. For example, KFD-2
+content can remain patch while an additive `registry.kind` field on the
+machine-consumed KFD registry schema records a minor `kfd-registry-schema`
+surface impact.
 
 Verify a release passport:
 

package/docs/versioning.md

@@ -46,6 +46,11 @@ The release passport records this as `surfaceImpacts[]` plus
 so an agent cannot silently label a release patch when one machine surface needs
 minor review.
 
+`surfaceImpacts[]` is mandatory for production release passports (`release/*`)
+and major publish-gate passports. Alpha, local, and legacy passport contexts
+keep the field optional so temporary validation can proceed without pretending
+to be a production release decision.
+
 Example: a KFD document such as KFD-2 is content and remains patch, but adding a
 `kind` field to the machine-consumed KFD `registry.json` is an additive change
 to the `kfd-registry-schema` surface and therefore requires minor-impact

package/package.json

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

package/packages/core/release-passport.js

@@ -59,6 +59,43 @@ function highestImpactLevel(levels = []) {
   return highest;
 }
 
+function surfaceImpactRequirement({ passport = {}, impact = {} } = {}) {
+  const release = passport?.release && typeof passport.release === "object" ? passport.release : {};
+  const impactRelease = impact?.release && typeof impact.release === "object" ? impact.release : {};
+  const channel = optionalString(release.channel || impactRelease.channel).toLowerCase();
+  const targetRef = optionalString(
+    release.targetRef ||
+    release.target_ref ||
+    impactRelease.targetRef ||
+    impactRelease.target_ref,
+  ).toLowerCase();
+  if (channel === "release" || targetRef.startsWith("release/")) {
+    return {
+      required: true,
+      type: "production-release",
+      reason: "production release passports require surfaceImpacts[] so agents can audit the final version impact",
+      channel,
+      targetRef,
+    };
+  }
+  if (channel === "major" || targetRef === "publish-gate/major" || targetRef === "major-gate") {
+    return {
+      required: true,
+      type: "major-gate",
+      reason: "major publish gates require surfaceImpacts[] so breaking-surface rationale is explicit",
+      channel,
+      targetRef,
+    };
+  }
+  return {
+    required: false,
+    type: channel || (targetRef ? "non-production-release" : "legacy"),
+    reason: "surfaceImpacts[] is optional for alpha, local, and legacy passport contexts",
+    channel,
+    targetRef,
+  };
+}
+
 function stableJson(value) {
   if (Array.isArray(value)) {
     return `[${value.map(stableJson).join(",")}]`;
@@ -1132,6 +1169,10 @@ export function createReleaseCheckReport({
   const passportSurfaceImpacts = Array.isArray(passport?.surfaceImpacts) ? passport.surfaceImpacts : [];
   const declaredFinalImpact = normalizeImpactLevel(impact?.versionImpact?.final || impact?.classification);
   const computedFinalImpact = highestImpactLevel(surfaceImpacts.map((entry) => entry.impact));
+  const requiredSurfaceImpacts = surfaceImpactRequirement({ passport, impact });
+  if (requiredSurfaceImpacts.required && surfaceImpacts.length === 0) {
+    issues.push(issue("error", "impact.surfaceImpacts.required", "surfaceImpacts[] is required for this release passport type", requiredSurfaceImpacts));
+  }
   if (surfaceImpacts.length > 0) {
     for (const [index, entry] of surfaceImpacts.entries()) {
       if (!entry.id) {
@@ -1167,6 +1208,7 @@ export function createReleaseCheckReport({
     checkedAt,
     ok,
     trust: ok ? "pass" : "fail",
+    surfaceImpactRequirement: requiredSurfaceImpacts,
     completeness: {
       artifactCount: artifacts.length,
       evidenceArtifactCount: evidenceArtifacts.length,
@@ -1182,6 +1224,7 @@ export function createReleaseCheckReport({
       impactPresent: Boolean(impact),
       agentIndexPresent: Boolean(agentIndex),
       productMechanismPresent: Boolean(productMechanism),
+      surfaceImpactsRequired: requiredSurfaceImpacts.required,
       surfaceImpactCount: surfaceImpacts.length,
       versionImpact: impact?.versionImpact?.final || "",
     },
@@ -1278,6 +1321,7 @@ export async function explainReleasePassport({ passportLocation, forAudience = "
     impact: {
       versionImpact: passport.versionImpact || {},
       surfaceImpacts: Array.isArray(passport.surfaceImpacts) ? passport.surfaceImpacts : [],
+      surfaceImpactRequirement: report.surfaceImpactRequirement,
       breaking: Boolean(passport.versionImpact?.final === "major"),
       migrationRequired: Boolean(passport.versionImpact?.final === "major"),
       summary: passport.versionImpact?.rationale || "",