gsdd-cli 0.27.0 → 0.29.0

package/bin/lib/lifecycle-preflight.mjs

@@ -1,17 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join, resolve } from 'path';
+import { isAbsolute, join, relative, resolve } from 'path';
 import { output } from './cli-utils.mjs';
 import { buildControlMap } from './control-map.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';
 
 const SURFACE_POLICIES = {
@@ -53,11 +44,6 @@ const SURFACE_POLICIES = {
     ownedWrites: ['spec', 'roadmap', 'phase-directories'],
     explicitLifecycleMutation: 'none',
   },
-  'plan-milestone-gaps': {
-    classification: 'owned_write',
-    ownedWrites: ['roadmap', 'phase-directories'],
-    explicitLifecycleMutation: 'none',
-  },
   resume: {
     classification: 'owned_write',
     ownedWrites: ['checkpoint-cleanup'],
@@ -65,17 +51,6 @@ 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']);
-const PREFLIGHT_CONTROL_MAP_SKIP_CODES = Object.freeze(['planning_state_drift']);
 const WORK_PHASE_LINE_RE = /^\s*[-*]\s*\[([ x-])\]\s*\*\*Phase\s+(\d+(?:\.\d+)*[A-Za-z]?):\s*(.+?)\*\*/i;
 
 export function evaluateLifecyclePreflight({
@@ -96,18 +71,25 @@ export function evaluateLifecyclePreflight({
 
   const lifecycle = evaluateLifecycleState({ planningDir });
   const normalizedPhase = phaseNumber ? normalizePhaseToken(phaseNumber) : null;
+  const usesBrownfieldAuthority = surface === 'plan' && normalizedPhase === 'brownfield-change';
+  const usesPlanAmendAuthority = surface === 'plan' && normalizedPhase === 'amend';
   const workMilestone = normalizedPhase ? evaluateWorkMilestoneState({ planningDir, phaseToken: normalizedPhase }) : null;
   const checkpointPath = join(planningDir, '.continue-here.md');
+  const stateLabel = createStateLabeler(planningDir);
   const resumeWorkCheckpoint = surface === 'resume'
     ? evaluateResumeWorkCheckpoint({ planningDir, checkpointPath })
     : null;
   const usesWorkAuthority = Boolean(workMilestone?.phaseEntry || resumeWorkCheckpoint);
+  const usesAlternateAuthority = usesWorkAuthority || usesBrownfieldAuthority || usesPlanAmendAuthority;
+  const ownedWrites = usesPlanAmendAuthority
+    ? [...policy.ownedWrites, 'roadmap', 'phase-directories']
+    : policy.ownedWrites;
   const specPath = join(planningDir, 'SPEC.md');
   const milestonesPath = join(planningDir, 'MILESTONES.md');
   const blockers = [];
 
   if (!existsSync(planningDir)) {
-    blockers.push(blocker('missing_planning_dir', '.planning/ does not exist yet.', ['.planning/']));
+    blockers.push(blocker('missing_planning_dir', `${stateLabel('.')} does not exist yet.`, [stateLabel('.')]));
   }
 
   if (expectsMutation !== 'none' && expectsMutation !== policy.explicitLifecycleMutation) {
@@ -124,83 +106,72 @@ export function evaluateLifecyclePreflight({
     blockers.push(blocker('missing_phase_argument', `${surface} requires an explicit phase number.`, []));
   }
 
-  if (normalizedPhase) {
+  if (usesBrownfieldAuthority) {
+    if (!lifecycle.brownfieldChange?.exists) {
+      blockers.push(
+        blocker(
+          'missing_brownfield_change',
+          `Brownfield-change planning requires an active ${stateLabel('brownfield-change', 'CHANGE.md')} continuity anchor.`,
+          [stateLabel('brownfield-change', 'CHANGE.md')]
+        )
+      );
+    } else if (String(lifecycle.brownfieldChange.currentStatus || '').toLowerCase() === 'closed') {
+      blockers.push(
+        blocker(
+          'brownfield_change_closed',
+          'Brownfield-change planning cannot continue because CHANGE.md marks the change closed.',
+          [stateLabel('brownfield-change', 'CHANGE.md')]
+        )
+      );
+    }
+  }
+
+  if (normalizedPhase && !usesBrownfieldAuthority && !usesPlanAmendAuthority) {
     blockers.push(
       ...(usesWorkAuthority
         ? buildWorkPhaseBlockers({ workMilestone, phaseToken: normalizedPhase, surface })
-        : buildPhaseBlockers({ lifecycle, phaseToken: normalizedPhase, surface }))
+        : buildPhaseBlockers({ lifecycle, phaseToken: normalizedPhase, surface, stateLabel }))
     );
   }
 
   if (surface === 'audit-milestone') {
-    blockers.push(...buildRoadmapAlignmentBlockers(lifecycle));
-    blockers.push(...buildAuditBlockers(lifecycle));
+    blockers.push(...buildRoadmapAlignmentBlockers(lifecycle, stateLabel));
+    blockers.push(...buildAuditBlockers(lifecycle, { stateLabel }));
   }
 
   if (surface === 'complete-milestone') {
-    blockers.push(...buildRoadmapAlignmentBlockers(lifecycle));
-    blockers.push(...buildAuditBlockers(lifecycle, { allowArchivedBlocker: true }));
+    blockers.push(...buildRoadmapAlignmentBlockers(lifecycle, stateLabel));
+    blockers.push(...buildAuditBlockers(lifecycle, { allowArchivedBlocker: true, stateLabel }));
     blockers.push(...buildCompletionBlockers(planningDir, lifecycle));
   }
 
   if (surface === 'new-milestone') {
-    blockers.push(...buildRoadmapAlignmentBlockers(lifecycle));
+    blockers.push(...buildRoadmapAlignmentBlockers(lifecycle, stateLabel));
     if (!existsSync(specPath)) {
-      blockers.push(blocker('missing_spec', 'SPEC.md is required before starting a new milestone.', ['.planning/SPEC.md']));
+      blockers.push(blocker('missing_spec', 'SPEC.md is required before starting a new milestone.', [stateLabel('SPEC.md')]));
     }
     if (!existsSync(milestonesPath)) {
-      blockers.push(blocker('missing_milestones', 'MILESTONES.md is required before starting a new milestone.', ['.planning/MILESTONES.md']));
+      blockers.push(blocker('missing_milestones', 'MILESTONES.md is required before starting a new milestone.', [stateLabel('MILESTONES.md')]));
     }
     if (lifecycle.currentMilestone.version && lifecycle.currentMilestone.archiveState !== 'archived') {
       blockers.push(
         blocker(
           'active_milestone_in_progress',
           `Milestone ${lifecycle.currentMilestone.version} is still active. Archive or remove the active roadmap before starting the next milestone.`,
-          ['.planning/ROADMAP.md']
+          [stateLabel('ROADMAP.md')]
         )
       );
     }
   }
 
   if (surface === 'resume' && !existsSync(checkpointPath) && lifecycle.nonPhaseState !== 'active_brownfield_change') {
-    blockers.push(blocker('missing_checkpoint', 'resume requires .planning/.continue-here.md unless an active .planning/brownfield-change/CHANGE.md continuity anchor exists.', ['.planning/.continue-here.md', '.planning/brownfield-change/CHANGE.md']));
+    const checkpointLabel = stateLabel('.continue-here.md');
+    const brownfieldLabel = stateLabel('brownfield-change', 'CHANGE.md');
+    blockers.push(blocker('missing_checkpoint', `resume requires ${checkpointLabel} unless an active ${brownfieldLabel} continuity anchor exists.`, [checkpointLabel, brownfieldLabel]));
   }
 
   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) {
-      const driftNotice = {
-        code: 'planning_state_drift',
-        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' && !usesWorkAuthority) {
-        blockers.push(driftNotice);
-      } else {
-        const workWarningContext = resumeWorkCheckpoint
-          ? 'because the checkpoint points at .work/milestone continuity'
-          : `by .work/milestone for Phase ${normalizedPhase}`;
-        warnings.push({
-          ...driftNotice,
-          message: usesWorkAuthority
-            ? `Planning state has drifted since the last recorded session, but ${surface} is using work_milestone authority ${workWarningContext}: ${drift.details.join('; ')}`
-            : `Planning state has drifted since the last recorded session: ${drift.details.join('; ')}`,
-        });
-      }
-    }
-  }
+  const planningState = null;
 
   const controlMap = buildPreflightControlMap({
     planningDir,
@@ -213,11 +184,11 @@ export function evaluateLifecyclePreflight({
     else warnings.push(notice);
   }
 
-  if (!usesWorkAuthority && lifecycle.phaseStatusAlignment.mismatches.length > 0) {
+  if (!usesAlternateAuthority && lifecycle.phaseStatusAlignment.mismatches.length > 0) {
     warnings.push({
       code: 'roadmap_phase_status_mismatch',
       message: `ROADMAP.md overview/detail phase statuses disagree: ${lifecycle.phaseStatusAlignment.mismatches.join('; ')}`,
-      artifacts: ['.planning/ROADMAP.md'],
+      artifacts: [stateLabel('ROADMAP.md')],
     });
   }
 
@@ -225,11 +196,10 @@ export function evaluateLifecyclePreflight({
     surface,
     phase: normalizedPhase,
     classification: policy.classification,
-    ownedWrites: policy.ownedWrites,
+    ownedWrites,
     explicitLifecycleMutation: policy.explicitLifecycleMutation,
-    closureEvidence: describeEvidenceSurface(surface),
     mutationRequest: expectsMutation,
-    authority: usesWorkAuthority ? 'work_milestone' : 'planning',
+    authority: usesPlanAmendAuthority ? 'plan_amend' : usesBrownfieldAuthority ? 'brownfield_change' : usesWorkAuthority ? 'work_milestone' : 'planning',
     allowed: blockers.length === 0,
     status: blockers.length === 0 ? 'allowed' : 'blocked',
     reason: blockers[0]?.code ?? null,
@@ -238,7 +208,7 @@ export function evaluateLifecyclePreflight({
     planningState,
     controlMap: controlMap.summary,
     lifecycle: {
-      authority: usesWorkAuthority ? 'work_milestone' : 'planning',
+      authority: usesPlanAmendAuthority ? 'plan_amend' : usesBrownfieldAuthority ? 'brownfield_change' : usesWorkAuthority ? 'work_milestone' : 'planning',
       currentMilestone: lifecycle.currentMilestone,
       currentPhase: lifecycle.currentPhase ? lifecycle.currentPhase.number : null,
       nextPhase: lifecycle.nextPhase ? lifecycle.nextPhase.number : null,
@@ -252,6 +222,20 @@ export function evaluateLifecyclePreflight({
             source: resumeWorkCheckpoint ? 'checkpoint' : 'phase',
           }
         : null,
+      brownfieldChange: usesBrownfieldAuthority
+        ? {
+            path: stateLabel('brownfield-change', 'CHANGE.md'),
+            status: lifecycle.brownfieldChange.currentStatus,
+            title: lifecycle.brownfieldChange.title,
+            nextAction: lifecycle.brownfieldChange.nextAction,
+          }
+        : null,
+      planAmend: usesPlanAmendAuthority
+        ? {
+            target: 'amend',
+            path: stateLabel('ROADMAP.md'),
+          }
+        : null,
     },
   };
 }
@@ -268,11 +252,11 @@ function buildPreflightControlMap({ planningDir, policy, existingBlockerCodes, c
     planningDir,
   });
   const risks = (map.risks || []).filter((risk) => (
-    !PREFLIGHT_CONTROL_MAP_SKIP_CODES.includes(risk.code)
-    && !(existingBlockerCodes.has(risk.code) && risk.severity !== 'block')
+    !(existingBlockerCodes.has(risk.code) && risk.severity !== 'block')
   ));
+  const stateLabel = createStateLabeler(planningDir);
   const notices = risks.map((risk) => ({
-    ...controlMapNotice(risk),
+    ...controlMapNotice(risk, stateLabel),
     severity: risk.severity || 'info',
   }));
 
@@ -288,17 +272,17 @@ function buildPreflightControlMap({ planningDir, policy, existingBlockerCodes, c
   };
 }
 
-function controlMapNotice(risk) {
+function controlMapNotice(risk, stateLabel) {
   return {
     code: risk.code,
     source: 'control-map',
     message: risk.message,
-    artifacts: ['gsdd control-map --json'],
+    artifacts: [`node ${stateLabel('bin', 'gsdd.mjs')} control-map --json`],
     risk,
   };
 }
 
-function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
+function buildPhaseBlockers({ lifecycle, phaseToken, surface, stateLabel }) {
   const blockers = [];
   const phaseEntry = lifecycle.phases.find((phase) => phase.number === phaseToken);
   if (!phaseEntry) {
@@ -306,7 +290,7 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
       blocker(
         'missing_phase',
         `Phase ${phaseToken} was not found in the active roadmap.`,
-        ['.planning/ROADMAP.md']
+        [stateLabel('ROADMAP.md')]
       )
     );
     return blockers;
@@ -324,7 +308,7 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
         blocker(
           'missing_plan',
           `Phase ${phaseToken} cannot execute because no PLAN artifact exists.`,
-          ['.planning/phases/']
+          [stateLabel('phases')]
         )
       );
     } else if (pendingPlans.length === 0) {
@@ -343,7 +327,7 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
       blocker(
         'phase_already_complete',
         `Phase ${phaseToken} is already complete and should not be planned again.`,
-        ['.planning/ROADMAP.md']
+        [stateLabel('ROADMAP.md')]
       )
     );
   }
@@ -354,7 +338,7 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
         blocker(
           'missing_plan',
           `Phase ${phaseToken} cannot be verified because no PLAN artifact exists.`,
-          ['.planning/phases/']
+          [stateLabel('phases')]
         )
       );
     }
@@ -363,7 +347,7 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
         blocker(
           'missing_summary',
           `Phase ${phaseToken} cannot be verified because no SUMMARY artifact exists yet.`,
-          ['.planning/phases/']
+          [stateLabel('phases')]
         )
       );
     }
@@ -552,21 +536,21 @@ function buildWorkPhaseBlockers({ workMilestone, phaseToken, surface }) {
   return blockers;
 }
 
-function buildRoadmapAlignmentBlockers(lifecycle) {
+function buildRoadmapAlignmentBlockers(lifecycle, stateLabel) {
   if (lifecycle.phaseStatusAlignment.mismatches.length === 0) return [];
   return [
     blocker(
       'roadmap_phase_status_mismatch',
       `ROADMAP.md overview/detail phase statuses disagree: ${lifecycle.phaseStatusAlignment.mismatches.join('; ')}`,
-      ['.planning/ROADMAP.md']
+      [stateLabel('ROADMAP.md')]
     ),
   ];
 }
 
-function buildAuditBlockers(lifecycle, { allowArchivedBlocker = false } = {}) {
+function buildAuditBlockers(lifecycle, { allowArchivedBlocker = false, stateLabel } = {}) {
   const blockers = [];
   if (!lifecycle.currentMilestone.version) {
-    blockers.push(blocker('missing_milestone', 'No active or retained milestone could be derived from ROADMAP.md.', ['.planning/ROADMAP.md']));
+    blockers.push(blocker('missing_milestone', 'No active or retained milestone could be derived from ROADMAP.md.', [stateLabel('ROADMAP.md')]));
     return blockers;
   }
 
@@ -575,19 +559,19 @@ function buildAuditBlockers(lifecycle, { allowArchivedBlocker = false } = {}) {
       blocker(
         allowArchivedBlocker ? 'milestone_already_archived' : 'milestone_already_archived',
         `Milestone ${lifecycle.currentMilestone.version} is already archived-with-ROADMAP.md evidence.`,
-        ['.planning/ROADMAP.md', '.planning/MILESTONES.md']
+        [stateLabel('ROADMAP.md'), stateLabel('MILESTONES.md')]
       )
     );
   }
 
   if (lifecycle.counts.total === 0) {
-    blockers.push(blocker('missing_phases', 'No active milestone phases were found in ROADMAP.md.', ['.planning/ROADMAP.md']));
+    blockers.push(blocker('missing_phases', 'No active milestone phases were found in ROADMAP.md.', [stateLabel('ROADMAP.md')]));
   } else if (lifecycle.counts.completed !== lifecycle.counts.total) {
     blockers.push(
       blocker(
         'incomplete_phases',
         `Milestone ${lifecycle.currentMilestone.version} still has incomplete phases (${lifecycle.counts.completed}/${lifecycle.counts.total} complete).`,
-        ['.planning/ROADMAP.md']
+        [stateLabel('ROADMAP.md')]
       )
     );
   }
@@ -602,7 +586,7 @@ function buildAuditBlockers(lifecycle, { allowArchivedBlocker = false } = {}) {
       blocker(
         'missing_verification',
         `Completed phases are missing VERIFICATION artifacts (${phasesMissingVerification.join(', ')}).`,
-        ['.planning/phases/']
+        [stateLabel('phases')]
       )
     );
   }
@@ -611,13 +595,14 @@ function buildAuditBlockers(lifecycle, { allowArchivedBlocker = false } = {}) {
 }
 
 function buildCompletionBlockers(planningDir, lifecycle) {
+  const stateLabel = createStateLabeler(planningDir);
   const auditPath = join(planningDir, `${lifecycle.currentMilestone.version}-MILESTONE-AUDIT.md`);
   if (!existsSync(auditPath)) {
     return [
       blocker(
         'missing_milestone_audit',
         `Milestone ${lifecycle.currentMilestone.version} cannot be completed without a milestone audit artifact.`,
-        [auditPath]
+        [stateLabel(`${lifecycle.currentMilestone.version}-MILESTONE-AUDIT.md`)]
       ),
     ];
   }
@@ -630,194 +615,14 @@ function buildCompletionBlockers(planningDir, lifecycle) {
       blocker(
         'audit_not_passed',
         `Milestone ${lifecycle.currentMilestone.version} requires a passed audit before completion.`,
-        [auditPath]
+        [stateLabel(`${lifecycle.currentMilestone.version}-MILESTONE-AUDIT.md`)]
       ),
     ];
   }
 
-  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] : '';
@@ -828,136 +633,6 @@ function readTopLevelScalar(frontmatter, key) {
   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()
@@ -1000,6 +675,17 @@ function blocker(code, message, artifacts) {
   return { code, message, artifacts };
 }
 
+function createStateLabeler(planningDir) {
+  const workspaceRoot = resolve(planningDir, '..');
+  return (...segments) => {
+    const targetPath = resolve(join(planningDir, ...segments));
+    const label = relative(workspaceRoot, targetPath);
+    if (label === '') return '.';
+    if (!label.startsWith('..') && !isAbsolute(label)) return label.replace(/\\/g, '/');
+    return targetPath.replace(/\\/g, '/');
+  };
+}
+
 export function cmdLifecyclePreflight(...args) {
   const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
   if (invalid) {
@@ -1008,9 +694,10 @@ export function cmdLifecyclePreflight(...args) {
     return;
   }
   const [surface, maybePhase, ...rest] = normalizedArgs;
+  const stateLabel = createStateLabeler(planningDir);
 
   if (!surface) {
-    console.error('Usage: node .planning/bin/gsdd.mjs lifecycle-preflight <surface> [phase] [--expects-mutation <none|phase-status>]');
+    console.error(`Usage: node ${stateLabel('bin', 'gsdd.mjs')} lifecycle-preflight <surface> [phase] [--expects-mutation <none|phase-status>]`);
     process.exitCode = 1;
     return;
   }