Enforce release claim closeout contract (#95)

* fix: enforce release claim closeout contract

* fix: scope release closeout contradictions

* fix: harden repo closeout boundaries

* fix: harden release closeout parsing

* fix: align delivery-sensitive closeout contract

* fix: fail closed on release metadata drift

* fix: reject unknown release contradiction checks

* fix: harden release contradiction validation

Author: PatrickSys

bin/lib/evidence-contract.mjs

@@ -1,6 +1,11 @@
 const EVIDENCE_KINDS = Object.freeze(['code', 'test', 'runtime', 'delivery', 'human']);
 const DELIVERY_POSTURES = Object.freeze(['repo_only', 'delivery_sensitive']);
 const CLOSURE_SURFACES = Object.freeze(['verify', 'audit-milestone', 'complete-milestone']);
+const RELEASE_CLAIM_POSTURES = Object.freeze([
+  'repo_closeout',
+  'runtime_validated_closeout',
+  'delivery_supported_closeout',
+]);
 
 const LEGACY_EVIDENCE_ALIASES = Object.freeze({
   code: 'code',
@@ -22,8 +27,8 @@ const EVIDENCE_MATRIX = Object.freeze({
       blockedSoloKinds: Object.freeze(['human', 'delivery']),
     }),
     delivery_sensitive: Object.freeze({
-      requiredKinds: Object.freeze(['code', 'runtime']),
-      recommendedKinds: Object.freeze(['test', 'delivery', 'human']),
+      requiredKinds: Object.freeze(['code', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['test', 'human']),
       blockedSoloKinds: Object.freeze(['code', 'human']),
     }),
   }),
@@ -53,7 +58,45 @@ const EVIDENCE_MATRIX = Object.freeze({
   }),
 });
 
-export { CLOSURE_SURFACES, DELIVERY_POSTURES, EVIDENCE_KINDS };
+const CONTRADICTION_CATEGORIES = Object.freeze([
+  'evidence',
+  'public_surface',
+  'runtime',
+  'delivery',
+  'planning_drift',
+  'generated_surface',
+]);
+
+const CONTRADICTION_STATUSES = Object.freeze(['passed', 'failed', 'not_applicable']);
+
+const RELEASE_CLAIM_MATRIX = Object.freeze({
+  repo_closeout: Object.freeze({
+    deliveryPosture: 'repo_only',
+    requiredClaimKinds: Object.freeze([]),
+    allowedClaim: 'Repo-local milestone or phase closeout is supported by planning and repository artifacts only.',
+    invalidClaim: 'Do not imply runtime validation, delivery, publication, or public support from repo-local closeout alone.',
+  }),
+  runtime_validated_closeout: Object.freeze({
+    deliveryPosture: 'repo_only',
+    requiredClaimKinds: Object.freeze(['runtime']),
+    allowedClaim: 'Runtime behavior or a runtime surface was directly executed and observed for the named runtime or surface.',
+    invalidClaim: 'Do not generalize validation from one runtime or generated surface to another.',
+  }),
+  delivery_supported_closeout: Object.freeze({
+    deliveryPosture: 'delivery_sensitive',
+    requiredClaimKinds: Object.freeze([]),
+    allowedClaim: 'Externally consumed release, support, install, or delivery claims are supported by the delivery-sensitive evidence bar.',
+    invalidClaim: 'Do not imply merge, package, tag, GitHub Release, publication, generated-surface freshness, or public support without matching delivery evidence.',
+  }),
+});
+
+const CONTRADICTION_BLOCKERS_BY_POSTURE = Object.freeze({
+  repo_closeout: Object.freeze(['evidence', 'public_surface', 'planning_drift']),
+  runtime_validated_closeout: Object.freeze(['evidence', 'runtime', 'generated_surface', 'planning_drift']),
+  delivery_supported_closeout: CONTRADICTION_CATEGORIES,
+});
+
+export { CLOSURE_SURFACES, DELIVERY_POSTURES, EVIDENCE_KINDS, RELEASE_CLAIM_POSTURES };
 
 export function normalizeEvidenceKind(kind) {
   if (!kind) {
@@ -78,6 +121,11 @@ export function isClosureSurface(surface) {
   return CLOSURE_SURFACES.includes(surface);
 }
 
+export function normalizeReleaseClaimPosture(posture) {
+  if (!posture) return 'repo_closeout';
+  return RELEASE_CLAIM_POSTURES.includes(posture) ? posture : null;
+}
+
 export function getEvidenceContract(surface, deliveryPosture) {
   const matrix = EVIDENCE_MATRIX[surface];
   if (!matrix) {
@@ -108,5 +156,170 @@ export function describeEvidenceSurface(surface) {
     surface,
     supportedKinds: [...EVIDENCE_KINDS],
     deliveryPostures: DELIVERY_POSTURES.map((deliveryPosture) => getEvidenceContract(surface, deliveryPosture)),
+    releaseClaimPostures: RELEASE_CLAIM_POSTURES.map((releaseClaimPosture) => getReleaseClaimContract(surface, releaseClaimPosture)),
+  };
+}
+
+function uniqueKinds(kinds) {
+  return [...new Set(kinds)];
+}
+
+function getDowngradePosture(observedKinds) {
+  if (observedKinds.includes('runtime')) {
+    return 'runtime_validated_closeout';
+  }
+  return 'repo_closeout';
+}
+
+export function getReleaseClaimContract(surface, releaseClaimPosture = 'repo_closeout') {
+  const posture = normalizeReleaseClaimPosture(releaseClaimPosture);
+  if (!posture) {
+    throw new Error(`Unsupported release claim posture: ${releaseClaimPosture}`);
+  }
+  const claim = RELEASE_CLAIM_MATRIX[posture];
+  const evidence = getEvidenceContract(surface, claim.deliveryPosture);
+  const requiredKinds = uniqueKinds([...evidence.requiredKinds, ...claim.requiredClaimKinds]);
+
+  return {
+    surface,
+    releaseClaimPosture: posture,
+    deliveryPosture: claim.deliveryPosture,
+    supportedKinds: [...EVIDENCE_KINDS],
+    requiredKinds,
+    requiredClaimKinds: [...claim.requiredClaimKinds],
+    allowedClaim: claim.allowedClaim,
+    invalidClaim: claim.invalidClaim,
+    waiverRule: 'Waivers may only narrow the release claim posture or defer an unsupported claim; they never satisfy missing required evidence for the stronger claim.',
+    deferralRule: 'Deferrals must name the unsupported claim, missing evidence kinds, and later workflow or milestone candidate when known.',
+    contradictionCategories: [...CONTRADICTION_CATEGORIES],
+  };
+}
+
+export function evaluateReleaseClaimPosture({
+  surface,
+  releaseClaimPosture = 'repo_closeout',
+  observedKinds = [],
+  waivedKinds = [],
+} = {}) {
+  const contract = getReleaseClaimContract(surface, releaseClaimPosture);
+  const observed = normalizeEvidenceKinds(observedKinds);
+  const waived = normalizeEvidenceKinds(waivedKinds);
+  const missingKinds = contract.requiredKinds.filter((kind) => !observed.includes(kind));
+  const invalidWaivers = waived.filter((kind) => missingKinds.includes(kind));
+  const hasUnsupportedStrongClaim = contract.releaseClaimPosture !== 'repo_closeout' && missingKinds.length > 0;
+
+  return {
+    surface: contract.surface,
+    releaseClaimPosture: contract.releaseClaimPosture,
+    deliveryPosture: contract.deliveryPosture,
+    requiredKinds: [...contract.requiredKinds],
+    observedKinds: observed,
+    missingKinds,
+    invalidWaivers,
+    status: missingKinds.length === 0 && invalidWaivers.length === 0 ? 'supported' : 'unsupported',
+    disposition: hasUnsupportedStrongClaim ? 'downgrade_or_defer' : missingKinds.length > 0 ? 'block_or_defer' : 'proceed',
+    downgradeTo: hasUnsupportedStrongClaim ? getDowngradePosture(observed) : null,
+    deferredClaims: hasUnsupportedStrongClaim
+      ? [{ claim: contract.releaseClaimPosture, missingKinds }]
+      : [],
+  };
+}
+
+export function evaluateReleaseClaimCloseoutContract({
+  surface,
+  deliveryPosture = null,
+  releaseClaimPosture = 'repo_closeout',
+  observedKinds = [],
+  waivedKinds = [],
+  unsupportedClaims = [],
+  deferrals = [],
+  contradictionChecks = {},
+} = {}) {
+  const posture = evaluateReleaseClaimPosture({
+    surface,
+    releaseClaimPosture,
+    observedKinds,
+    waivedKinds,
+  });
+  const missingContradictionChecks = CONTRADICTION_CATEGORIES.filter((name) => !(name in contradictionChecks));
+  const failedContradictionChecks = Object.entries(contradictionChecks)
+    .filter(([, status]) => status === 'failed')
+    .map(([name]) => name);
+  const unknownContradictionChecks = Object.keys(contradictionChecks)
+    .filter((name) => !CONTRADICTION_CATEGORIES.includes(name));
+  const invalidContradictionChecks = Object.entries(contradictionChecks)
+    .filter(([, status]) => !CONTRADICTION_STATUSES.includes(status))
+    .map(([name]) => name);
+  const blockingContradictionChecks = failedContradictionChecks.filter((name) =>
+    CONTRADICTION_BLOCKERS_BY_POSTURE[posture.releaseClaimPosture].includes(name)
+  );
+  const unresolvedUnsupportedClaims = unsupportedClaims.filter((claim) =>
+    !deferrals.some((deferral) => namesUnsupportedClaim(deferral, claim))
+  );
+  const blockers = [];
+
+  if (deliveryPosture && deliveryPosture !== posture.deliveryPosture) {
+    blockers.push({
+      code: 'incompatible_release_claim_posture',
+      details: [`${deliveryPosture} cannot support ${posture.releaseClaimPosture}; expected ${posture.deliveryPosture}`],
+    });
+  }
+
+  if (posture.missingKinds.length > 0) {
+    blockers.push({ code: 'missing_required_release_evidence', details: posture.missingKinds });
+  }
+  if (posture.invalidWaivers.length > 0) {
+    blockers.push({ code: 'invalid_release_waivers', details: posture.invalidWaivers });
+  }
+  if (unresolvedUnsupportedClaims.length > 0) {
+    blockers.push({ code: 'unsupported_release_claims', details: unresolvedUnsupportedClaims });
+  }
+  if (missingContradictionChecks.length > 0) {
+    blockers.push({ code: 'missing_release_contradiction_checks', details: missingContradictionChecks });
+  }
+  if (unknownContradictionChecks.length > 0) {
+    blockers.push({ code: 'unknown_release_contradiction_checks', details: unknownContradictionChecks });
+  }
+  if (invalidContradictionChecks.length > 0) {
+    blockers.push({ code: 'invalid_release_contradiction_checks', details: invalidContradictionChecks });
+  }
+  if (blockingContradictionChecks.length > 0) {
+    blockers.push({ code: 'failed_release_contradiction_checks', details: blockingContradictionChecks });
+  }
+
+  return {
+    ...posture,
+    unsupportedClaims: [...unsupportedClaims],
+    deferrals: [...deferrals],
+    failedContradictionChecks: blockingContradictionChecks,
+    allFailedContradictionChecks: failedContradictionChecks,
+    missingContradictionChecks,
+    unknownContradictionChecks,
+    invalidContradictionChecks,
+    unresolvedUnsupportedClaims,
+    blockers,
+    status: blockers.length === 0 ? 'supported' : 'unsupported',
   };
 }
+
+function namesUnsupportedClaim(deferral, claim) {
+  const normalizedDeferral = normalizeClaimText(deferral);
+  const normalizedClaim = normalizeClaimText(claim);
+  if (!normalizedDeferral || !normalizedClaim) return false;
+  return normalizedDeferral.includes(normalizedClaim) && isStructuredDeferral(normalizedDeferral);
+}
+
+function isStructuredDeferral(normalizedDeferral) {
+  const namesEvidenceKind = EVIDENCE_KINDS.some((kind) => normalizedDeferral.includes(kind));
+  const namesLaterTarget = /\b(later|next|future|workflow|milestone|phase|gsdd)\b/.test(normalizedDeferral);
+  return namesEvidenceKind && namesLaterTarget;
+}
+
+function normalizeClaimText(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}