gsdd-cli 0.19.0 → 0.19.1

package/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();
+}

package/bin/lib/health-truth.mjs

@@ -56,8 +56,8 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
       warnings.push({
         id: 'W8',
         severity: 'WARN',
-        message: `distilled/README.md workflow inventory is out of sync (${issues.join('; ')})`,
-        fix: 'Update distilled/README.md workflow status table and framework file tree to match distilled/workflows/',
+        message: `distilled/README.md workflow surface/status inventory is out of sync (${issues.join('; ')})`,
+        fix: 'Update distilled/README.md workflow inventory table and framework file tree to match distilled/workflows/',
       });
     }
   }
@@ -105,8 +105,8 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
       id: 'W12',
       severity: 'WARN',
       message: `Planning state drifted since last recorded session (${drift.details.join('; ')})`,
-      fix: 'Review the changes, then run a lifecycle workflow to update the fingerprint',
-    });
+        fix: 'Review the changed planning files. If the drift is intentional, rebaseline with `node .planning/bin/gsdd.mjs session-fingerprint write`, then rerun the blocked lifecycle preflight.',
+      });
   }
 
   return warnings;
@@ -119,19 +119,34 @@ function extractHealthTableIds(content) {
 }
 
 function extractReadmeStatusEntries(content) {
-  const section = extractSection(content, '## Current Status', 'Architecture notes:');
+  const workflowSurface = extractSection(content, '## Workflow Surface', 'Architecture notes:');
+  const currentStatus = extractSection(content, '## Current Status', 'Architecture notes:');
+  const section = workflowSurface || currentStatus;
   if (!section) return [];
   return [...normalizeContent(section).matchAll(/\|\s*`([^`]+\.md)`\s*\|/g)].map((result) => result[1]);
 }
 
 function extractReadmeWorkflowTreeEntries(content) {
   const section = extractSection(content, '## Files In This Framework', '## ');
-  const match = normalizeContent(section || '').match(/```[\s\S]*?workflows\/\n([\s\S]*?)\n\s*templates\//);
+  const match = normalizeContent(section || '').match(/```[^\n]*\n([\s\S]*?)\n```/);
   if (!match) return [];
-  return match[1]
-    .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => line.endsWith('.md'));
+  const entries = [];
+  let inWorkflows = false;
+  for (const rawLine of match[1].split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (!inWorkflows) {
+      if (/\bworkflows\/$/.test(line)) inWorkflows = true;
+      continue;
+    }
+    if (/\.md\b/.test(line)) {
+      const file = line.match(/([^\s/`|├└─]+\.md)\b/);
+      if (file) entries.push(file[1]);
+      continue;
+    }
+    if (/\b[^\s/]+\/$/.test(line)) break;
+  }
+  return entries;
 }
 
 function extractRepoLocalPaths(content) {

package/bin/lib/health.mjs

@@ -179,7 +179,7 @@ export function createCmdHealth(ctx) {
     const lifecycle = evaluateLifecycleState({ planningDir });
 
     if (roadmap && existsSync(phasesDir)) {
-      for (const phase of lifecycle.phases.filter((entry) => entry.status !== 'not_started' && !entry.hasArtifacts)) {
+      for (const phase of lifecycle.phases.filter((entry) => entry.status !== 'not_started' && !entry.hasLifecycleArtifacts)) {
         warnings.push({
           id: 'W4',
           severity: 'WARN',

package/bin/lib/init-runtime.mjs

@@ -186,6 +186,7 @@ Commands:
   phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])
   lifecycle-preflight <surface> [phase]
                               Inspect deterministic lifecycle gate results for a workflow surface
+  session-fingerprint write    Rebaseline planning-state drift after reviewing changed planning files
   help                        Show this summary
 
 Platforms (for --tools):
@@ -254,6 +255,7 @@ Starting lanes after init:
 
 Advanced/internal helpers (kept available, but not the primary first-run user story):
   lifecycle-preflight       Inspect deterministic lifecycle gate results for a workflow surface
+  session-fingerprint       Rebaseline the local planning-state fingerprint after review
   phase-status              Update ROADMAP.md phase status through the local helper surface
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;