gsdd-cli 0.19.0 → 0.19.1

package/bin/lib/lifecycle-preflight.mjs

@@ -1,7 +1,14 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { output } from './cli-utils.mjs';
-import { describeEvidenceSurface } from './evidence-contract.mjs';
+import {
+  DELIVERY_POSTURES,
+  EVIDENCE_KINDS,
+  RELEASE_CLAIM_POSTURES,
+  describeEvidenceSurface,
+  evaluateReleaseClaimCloseoutContract,
+  getEvidenceContract,
+} from './evidence-contract.mjs';
 import { evaluateLifecycleState, normalizePhaseToken } from './lifecycle-state.mjs';
 import { checkDrift } from './session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
@@ -12,6 +19,12 @@ const SURFACE_POLICIES = {
     ownedWrites: [],
     explicitLifecycleMutation: 'none',
   },
+  plan: {
+    classification: 'owned_write',
+    ownedWrites: ['research', 'plan'],
+    explicitLifecycleMutation: 'none',
+    phaseRequired: true,
+  },
   execute: {
     classification: 'owned_write',
     ownedWrites: ['summary'],
@@ -46,6 +59,17 @@ const SURFACE_POLICIES = {
   },
 };
 
+const RELEASE_CONTRADICTION_CHECKS = Object.freeze([
+  'evidence',
+  'public_surface',
+  'runtime',
+  'delivery',
+  'planning_drift',
+  'generated_surface',
+]);
+
+const RELEASE_CONTRADICTION_STATUSES = Object.freeze(['passed', 'failed', 'not_applicable']);
+
 export function evaluateLifecyclePreflight({
   planningDir,
   surface,
@@ -125,15 +149,33 @@ export function evaluateLifecyclePreflight({
   }
 
   const warnings = [];
+  let planningState = null;
 
   if (existsSync(planningDir)) {
     const drift = checkDrift(planningDir);
+    planningState = {
+      classification: drift.classification,
+      drifted: drift.drifted,
+      noBaseline: drift.noBaseline,
+      details: drift.details,
+      files: drift.files,
+    };
     if (drift.drifted) {
-      warnings.push({
+      const driftNotice = {
         code: 'planning_state_drift',
-        message: `Planning state has drifted since the last recorded session: ${drift.details.join('; ')}`,
+        message: `${surface} cannot proceed because planning state drifted since the last recorded session: ${drift.details.join('; ')}`,
         artifacts: ['.planning/ROADMAP.md', '.planning/SPEC.md', '.planning/config.json'],
-      });
+        details: drift.details,
+        files: drift.files,
+      };
+      if (policy.classification === 'owned_write') {
+        blockers.push(driftNotice);
+      } else {
+        warnings.push({
+          ...driftNotice,
+          message: `Planning state has drifted since the last recorded session: ${drift.details.join('; ')}`,
+        });
+      }
     }
   }
 
@@ -158,6 +200,7 @@ export function evaluateLifecyclePreflight({
     reason: blockers[0]?.code ?? null,
     blockers,
     warnings,
+    planningState,
     lifecycle: {
       currentMilestone: lifecycle.currentMilestone,
       currentPhase: lifecycle.currentPhase ? lifecycle.currentPhase.number : null,
@@ -207,6 +250,16 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
     }
   }
 
+  if (surface === 'plan' && phaseEntry.status === 'done') {
+    blockers.push(
+      blocker(
+        'phase_already_complete',
+        `Phase ${phaseToken} is already complete and should not be planned again.`,
+        ['.planning/ROADMAP.md']
+      )
+    );
+  }
+
   if (surface === 'verify') {
     if (planArtifacts.length === 0) {
       blockers.push(
@@ -302,8 +355,9 @@ function buildCompletionBlockers(planningDir, lifecycle) {
   }
 
   const auditContent = readFileSync(auditPath, 'utf-8');
-  const statusMatch = auditContent.match(/^status:\s*(.+)$/m);
-  if (!statusMatch || statusMatch[1].trim() !== 'passed') {
+  const auditFrontmatter = extractFrontmatter(auditContent);
+  const auditStatus = readTopLevelScalar(auditFrontmatter || auditContent, 'status');
+  if (auditStatus !== 'passed') {
     return [
       blocker(
         'audit_not_passed',
@@ -313,9 +367,367 @@ function buildCompletionBlockers(planningDir, lifecycle) {
     ];
   }
 
+  const releaseContractBlockers = buildReleaseClaimCompletionBlockers(auditContent, auditPath);
+  if (releaseContractBlockers.length > 0) return releaseContractBlockers;
+
   return [];
 }
 
+function buildReleaseClaimCompletionBlockers(auditContent, auditPath) {
+  const frontmatter = extractFrontmatter(auditContent);
+  const deliveryPosture = readTopLevelScalar(frontmatter, 'delivery_posture');
+  const releaseClaimPosture = readTopLevelScalar(frontmatter, 'release_claim_posture');
+  const evidenceBlock = extractYamlBlock(frontmatter, 'evidence_contract');
+  const releaseBlock = extractYamlBlock(frontmatter, 'release_claim_contract');
+  const missing = [];
+
+  if (!deliveryPosture) missing.push('delivery_posture');
+  if (!releaseClaimPosture) missing.push('release_claim_posture');
+  if (!evidenceBlock) missing.push('evidence_contract');
+  if (!releaseBlock) missing.push('release_claim_contract');
+
+  if (missing.length > 0) {
+    return [blocker(
+      'missing_release_claim_contract',
+      `Milestone audit is missing release closeout metadata (${missing.join(', ')}). Re-run audit before completion.`,
+      [auditPath]
+    )];
+  }
+
+  const requiredKinds = readBlockList(evidenceBlock, 'required_kinds');
+  const observedKinds = readBlockList(evidenceBlock, 'observed_kinds');
+  const missingKinds = readBlockList(evidenceBlock, 'missing_kinds');
+  const unsupportedClaims = readBlockList(releaseBlock, 'unsupported_claims');
+  const waivedKinds = readBlockList(releaseBlock, 'waivers');
+  const deferrals = readBlockList(releaseBlock, 'deferrals');
+  const contradictionChecks = readNestedStatusBlock(releaseBlock, 'contradiction_checks');
+  const blockers = [];
+  const invalidEvidenceKinds = [
+    ...findInvalidEvidenceKinds('required_kinds', requiredKinds),
+    ...findInvalidEvidenceKinds('observed_kinds', observedKinds),
+    ...findInvalidEvidenceKinds('missing_kinds', missingKinds),
+    ...findInvalidEvidenceKinds('waivers', waivedKinds),
+  ];
+
+  if (requiredKinds.length === 0 && observedKinds.length === 0) {
+    blockers.push(blocker(
+      'missing_release_evidence_contract',
+      'Milestone audit evidence_contract must include required_kinds and observed_kinds before completion.',
+      [auditPath]
+    ));
+  }
+
+  if (!DELIVERY_POSTURES.includes(deliveryPosture)) {
+    blockers.push(blocker(
+      'invalid_delivery_posture',
+      `Milestone audit has invalid delivery_posture (${deliveryPosture}). Re-run audit before completion.`,
+      [auditPath]
+    ));
+  }
+
+  if (!RELEASE_CLAIM_POSTURES.includes(releaseClaimPosture)) {
+    blockers.push(blocker(
+      'invalid_release_claim_posture',
+      `Milestone audit has invalid release_claim_posture (${releaseClaimPosture}). Re-run audit before completion.`,
+      [auditPath]
+    ));
+  }
+
+  if (invalidEvidenceKinds.length > 0) {
+    blockers.push(blocker(
+      'invalid_release_evidence_kinds',
+      `Milestone audit has invalid release evidence kind values (${invalidEvidenceKinds.join(', ')}). Supported values are ${EVIDENCE_KINDS.join(', ')}.`,
+      [auditPath]
+    ));
+  }
+
+  const missingContradictionChecks = RELEASE_CONTRADICTION_CHECKS.filter((name) => !(name in contradictionChecks));
+  const unknownContradictionChecks = Object.keys(contradictionChecks)
+    .filter((name) => !RELEASE_CONTRADICTION_CHECKS.includes(name));
+  const invalidContradictionChecks = Object.entries(contradictionChecks)
+    .filter(([, status]) => !RELEASE_CONTRADICTION_STATUSES.includes(status))
+    .map(([name]) => name);
+
+  if (missingContradictionChecks.length > 0) {
+    blockers.push(blocker(
+      'missing_release_contradiction_checks',
+      `Milestone audit release_claim_contract.contradiction_checks is missing required checks (${missingContradictionChecks.join(', ')}).`,
+      [auditPath]
+    ));
+  }
+
+  if (invalidContradictionChecks.length > 0) {
+    blockers.push(blocker(
+      'invalid_release_contradiction_checks',
+      `Milestone audit release_claim_contract.contradiction_checks has invalid statuses (${invalidContradictionChecks.join(', ')}).`,
+      [auditPath]
+    ));
+  }
+
+  if (unknownContradictionChecks.length > 0) {
+    blockers.push(blocker(
+      'unknown_release_contradiction_checks',
+      `Milestone audit release_claim_contract.contradiction_checks has unknown checks (${unknownContradictionChecks.join(', ')}). Supported checks are ${RELEASE_CONTRADICTION_CHECKS.join(', ')}.`,
+      [auditPath]
+    ));
+  }
+
+  if (!DELIVERY_POSTURES.includes(deliveryPosture) || !RELEASE_CLAIM_POSTURES.includes(releaseClaimPosture)) {
+    return blockers;
+  }
+
+  const releaseEvaluation = evaluateReleaseClaimCloseoutContract({
+    surface: 'complete-milestone',
+    deliveryPosture,
+    releaseClaimPosture,
+    observedKinds,
+    waivedKinds,
+    unsupportedClaims,
+    deferrals,
+    contradictionChecks,
+  });
+
+  if (DELIVERY_POSTURES.includes(deliveryPosture)) {
+    const evidenceContract = getEvidenceContract('complete-milestone', deliveryPosture);
+    const enforcedRequiredKinds = [...new Set([...evidenceContract.requiredKinds, ...releaseEvaluation.requiredKinds])];
+    const undeclaredRequiredKinds = enforcedRequiredKinds.filter((kind) => !requiredKinds.includes(kind));
+    const recomputedMissingKinds = enforcedRequiredKinds.filter((kind) => !observedKinds.includes(kind));
+
+    if (undeclaredRequiredKinds.length > 0) {
+      blockers.push(blocker(
+        'invalid_release_evidence_contract',
+        `Milestone audit evidence_contract.required_kinds omits required closeout evidence (${undeclaredRequiredKinds.join(', ')}).`,
+        [auditPath]
+      ));
+    }
+
+    if (recomputedMissingKinds.length > 0) {
+      blockers.push(blocker(
+        'missing_required_release_evidence',
+        `Milestone audit observed evidence is missing required closeout kinds (${recomputedMissingKinds.join(', ')}).`,
+        [auditPath]
+      ));
+    }
+  }
+
+  if (missingKinds.length > 0) {
+    blockers.push(blocker(
+      'missing_required_release_evidence',
+      `Milestone audit is missing required evidence kinds for closeout (${missingKinds.join(', ')}).`,
+      [auditPath]
+    ));
+  }
+
+  if (releaseEvaluation.invalidWaivers.length > 0) {
+    blockers.push(blocker(
+      'invalid_release_waivers',
+      `Milestone audit has invalid waivers for missing required evidence (${releaseEvaluation.invalidWaivers.join(', ')}).`,
+      [auditPath]
+    ));
+  }
+  if (releaseEvaluation.blockers.some((releaseBlocker) => releaseBlocker.code === 'incompatible_release_claim_posture')) {
+    blockers.push(blocker(
+      'incompatible_release_claim_posture',
+      `Milestone audit release_claim_posture (${releaseClaimPosture}) is incompatible with delivery_posture (${deliveryPosture}).`,
+      [auditPath]
+    ));
+  }
+  if (releaseEvaluation.unresolvedUnsupportedClaims.length > 0) {
+    blockers.push(blocker(
+      'unsupported_release_claims',
+      `Milestone audit has unsupported release claims without downgrade or deferral (${releaseEvaluation.unresolvedUnsupportedClaims.join(', ')}).`,
+      [auditPath]
+    ));
+  }
+  if (releaseEvaluation.failedContradictionChecks.length > 0) {
+    blockers.push(blocker(
+      'failed_release_contradiction_checks',
+      `Milestone audit has failed release contradiction checks (${releaseEvaluation.failedContradictionChecks.join(', ')}).`,
+      [auditPath]
+    ));
+  }
+
+  return blockers;
+}
+
+function extractFrontmatter(content) {
+  const match = String(content || '').replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+  return match ? match[1] : '';
+}
+
+function readTopLevelScalar(frontmatter, key) {
+  const match = String(frontmatter || '').match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return match ? cleanYamlValue(match[1]) : null;
+}
+
+function extractYamlBlock(frontmatter, key) {
+  const lines = String(frontmatter || '').replace(/\r\n/g, '\n').split('\n');
+  const startIndex = lines.findIndex((line) => new RegExp(`^${key}:\\s*(?:#.*)?$`).test(line.trim()));
+  if (startIndex === -1) return '';
+
+  const collected = [];
+  for (const line of lines.slice(startIndex + 1)) {
+    if (/^[A-Za-z0-9_-]+:\s*/.test(line)) break;
+    collected.push(line);
+  }
+  return collected.join('\n');
+}
+
+function readBlockList(block, key) {
+  const lines = String(block || '').replace(/\r\n/g, '\n').split('\n');
+  const startIndex = lines.findIndex((line) => new RegExp(`^\\s+${key}:`).test(line));
+  if (startIndex === -1) return [];
+  const baseIndent = lines[startIndex].match(/^\s*/)[0].length;
+
+  const inline = lines[startIndex].match(/^\s+[^:]+:\s*\[([^\]]*)\]/);
+  if (inline) return splitInlineList(inline[1]);
+
+  const collected = [];
+  for (const line of lines.slice(startIndex + 1)) {
+    const indent = line.match(/^\s*/)[0].length;
+    if (line.trim() && indent <= baseIndent && /^\s*[A-Za-z0-9_-]+:\s*/.test(line)) break;
+    collected.push(line);
+  }
+
+  return parseYamlListItems(collected, baseIndent)
+    .map((item) => item.join(' '))
+    .map(cleanYamlValue);
+}
+
+function parseYamlListItems(lines, baseIndent) {
+  const items = [];
+  let current = null;
+  let itemIndent = null;
+
+  for (const line of lines) {
+    const match = line.match(/^(\s*)-\s*(.+?)\s*$/);
+    const indent = line.match(/^\s*/)[0].length;
+
+    if (match && indent > baseIndent && (itemIndent === null || indent === itemIndent)) {
+      if (current) items.push(current);
+      current = [match[2]];
+      itemIndent = indent;
+      continue;
+    }
+
+    if (current && line.trim()) {
+      current.push(line.trim());
+    }
+  }
+
+  if (current) items.push(current);
+  return items;
+}
+
+function findInvalidEvidenceKinds(field, kinds) {
+  return kinds
+    .filter((kind) => !EVIDENCE_KINDS.includes(kind))
+    .map((kind) => `${field}: ${kind}`);
+}
+
+function readNestedStatusBlock(block, key) {
+  const nested = extractIndentedBlock(block, key);
+  const statuses = {};
+  for (const line of nested.split('\n')) {
+    const match = line.match(/^\s+([A-Za-z0-9_-]+):\s*(.+)$/);
+    if (match) statuses[match[1]] = cleanYamlValue(match[2]);
+  }
+  return statuses;
+}
+
+function extractIndentedBlock(block, key) {
+  const lines = String(block || '').replace(/\r\n/g, '\n').split('\n');
+  const startIndex = lines.findIndex((line) => new RegExp(`^\\s+${key}:`).test(line));
+  if (startIndex === -1) return '';
+  const baseIndent = lines[startIndex].match(/^\s*/)[0].length;
+
+  const collected = [];
+  for (const line of lines.slice(startIndex + 1)) {
+    const indent = line.match(/^\s*/)[0].length;
+    if (line.trim() && indent <= baseIndent && /^\s*[A-Za-z0-9_-]+:\s*/.test(line)) break;
+    collected.push(line);
+  }
+  return collected.join('\n');
+}
+
+function splitInlineList(value) {
+  return splitCommaAware(value)
+    .map(cleanYamlValue)
+    .filter(Boolean);
+}
+
+function splitCommaAware(value) {
+  const items = [];
+  let current = '';
+  let quote = null;
+  let escaped = false;
+
+  for (const char of String(value || '')) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && quote) {
+      current += char;
+      escaped = true;
+      continue;
+    }
+    if ((char === '"' || char === "'") && (!quote || quote === char)) {
+      quote = quote ? null : char;
+      current += char;
+      continue;
+    }
+    if (char === ',' && !quote) {
+      items.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+
+  items.push(current);
+  return items;
+}
+
+function cleanYamlValue(value) {
+  return stripInlineYamlComment(String(value || ''))
+    .trim()
+    .replace(/^['"]|['"]$/g, '')
+    .trim();
+}
+
+function stripInlineYamlComment(value) {
+  let current = '';
+  let quote = null;
+  let escaped = false;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && quote) {
+      current += char;
+      escaped = true;
+      continue;
+    }
+    if ((char === '"' || char === "'") && (!quote || quote === char)) {
+      quote = quote ? null : char;
+      current += char;
+      continue;
+    }
+    if (char === '#' && !quote && (index === 0 || /\s/.test(value[index - 1]))) {
+      return current.trimEnd();
+    }
+    current += char;
+  }
+
+  return current;
+}
+
 function blocker(code, message, artifacts) {
   return { code, message, artifacts };
 }

package/bin/lib/lifecycle-state.mjs

@@ -42,6 +42,7 @@ export function evaluateLifecycleState({ planningDir, provenance = null } = {})
     return {
       ...phase,
       hasArtifacts: matchingArtifacts.length > 0,
+      hasLifecycleArtifacts: hasPlan || hasSummary,
       hasPlan,
       hasSummary,
       artifacts: matchingArtifacts,
@@ -339,10 +340,10 @@ function classifyPhaseArtifact(dir, name) {
   if (!baseIdMatch || !phaseTokenMatch) return null;
 
   let kind = 'other';
-  if (name.includes('PLAN')) kind = 'plan';
-  else if (name.includes('SUMMARY')) kind = 'summary';
-  else if (name.includes('VERIFICATION')) kind = 'verification';
-  else if (name.includes('APPROACH')) kind = 'approach';
+  if (isNamedPhaseArtifact(name, baseIdMatch[1], 'PLAN')) kind = 'plan';
+  else if (isNamedPhaseArtifact(name, baseIdMatch[1], 'SUMMARY')) kind = 'summary';
+  else if (isNamedPhaseArtifact(name, baseIdMatch[1], 'VERIFICATION')) kind = 'verification';
+  else if (isNamedPhaseArtifact(name, baseIdMatch[1], 'APPROACH')) kind = 'approach';
 
   return {
     dir,
@@ -354,6 +355,10 @@ function classifyPhaseArtifact(dir, name) {
   };
 }
 
+function isNamedPhaseArtifact(name, baseId, kind) {
+  return name.toLowerCase() === `${baseId.toLowerCase()}-${kind.toLowerCase()}.md`;
+}
+
 function parseMilestoneLedger(content) {
   if (!content) return [];
 

package/bin/lib/phase.mjs

@@ -72,13 +72,14 @@ function listPhaseArtifacts(dir) {
 }
 
 function classifyPhaseArtifact(dir, name) {
+  const baseIdMatch = name.match(/^(\d+(?:\.\d+)*[a-z]?(?:-\d+)?)/i);
   const dirMatch = dir ? dir.match(/^(\d+(?:\.\d+)*[a-z]?)-/i) : null;
   const nameMatch = name.match(/^(\d+(?:\.\d+)*[a-z]?)/i);
   const phaseToken = normalizePhaseToken((dirMatch || nameMatch)?.[1] || '');
 
   let kind = 'OTHER';
-  if (name.includes('PLAN')) kind = 'PLAN';
-  else if (name.includes('SUMMARY')) kind = 'SUMMARY';
+  if (baseIdMatch && isNamedPhaseArtifact(name, baseIdMatch[1], 'PLAN')) kind = 'PLAN';
+  else if (baseIdMatch && isNamedPhaseArtifact(name, baseIdMatch[1], 'SUMMARY')) kind = 'SUMMARY';
 
   return {
     dir,
@@ -89,6 +90,10 @@ function classifyPhaseArtifact(dir, name) {
   };
 }
 
+function isNamedPhaseArtifact(name, baseId, kind) {
+  return name.toLowerCase() === `${baseId.toLowerCase()}-${kind.toLowerCase()}.md`;
+}
+
 function padPhase(n) {
   return String(n).padStart(2, '0');
 }

package/bin/lib/plan-constants.mjs

@@ -7,6 +7,11 @@ export const PLAN_CHECK_DIMENSIONS = [
   'must_have_quality',
   'context_compliance',
   'goal_achievement',
+  'scope_boundaries',
+  'anti_regression_capture',
+  'escalation_integrity',
+  'closure_honesty',
+  'high_leverage_review',
   'approach_alignment',
 ];
 

package/bin/lib/rendering.mjs

@@ -46,12 +46,14 @@ function renderPlanningCliLauncher() {
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdPhaseStatus } from './lib/phase.mjs';
+import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const COMMANDS = {
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'phase-status': cmdPhaseStatus,
+  'session-fingerprint': cmdSessionFingerprint,
 };
 
 function printHelp() {
@@ -67,6 +69,8 @@ function printHelp() {
     '  lifecycle-preflight <surface> [phase]',
     '                               Inspect lifecycle gate results for a workflow surface',
     '                               Example: node .planning/bin/gsdd.mjs lifecycle-preflight verify 1 --expects-mutation phase-status',
+    '  session-fingerprint write',
+    '                               Rebaseline planning-state drift after reviewing changed planning files',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',