gsdd-cli 0.16.1 → 0.18.0

package/bin/lib/health.mjs

@@ -8,10 +8,12 @@ import { join } from 'path';
 import { readManifest, detectModifications } from './manifest.mjs';
 import { output } from './cli-utils.mjs';
 import { runTruthChecks, TRUTH_CHECK_IDS } from './health-truth.mjs';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import { evaluateRuntimeFreshness } from './runtime-freshness.mjs';
 
 /**
  * Factory function returning the health command.
- * ctx must provide: { frameworkVersion }
+ * ctx should provide: { frameworkVersion, workflows }
  */
 export function createCmdHealth(ctx) {
   return async function cmdHealth(...healthArgs) {
@@ -41,8 +43,10 @@ export function createCmdHealth(ctx) {
     // E1: config.json missing (already handled by pre-init guard, but keep for completeness)
     // E2: config.json missing required fields
     let config = null;
+    let configOk = false;
     try {
       config = JSON.parse(readFileSync(join(planningDir, 'config.json'), 'utf-8'));
+      configOk = true;
       const requiredFields = ['researchDepth', 'modelProfile', 'initVersion'];
       const missing = requiredFields.filter((f) => !(f in config));
       if (missing.length > 0) {
@@ -148,45 +152,28 @@ export function createCmdHealth(ctx) {
     const roadmapPath = join(planningDir, 'ROADMAP.md');
     const phasesDir = join(planningDir, 'phases');
     const roadmap = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : null;
-    const phaseArtifacts = existsSync(phasesDir) ? listPhaseArtifacts(phasesDir) : [];
+    const lifecycle = evaluateLifecycleState({ planningDir });
 
     if (roadmap && existsSync(phasesDir)) {
-      const phaseLabels = [];
-      let inDetails = false;
-      for (const line of roadmap.split('\n')) {
-        if (line.includes('<details>') && !line.includes('</details>')) {
-          inDetails = true;
-          continue;
-        }
-        if (line.includes('</details>')) {
-          inDetails = false;
-          continue;
-        }
-        if (inDetails) continue;
-        const match = line.match(/^\s*[-*]\s*\[([x-])\]\s*\*\*Phase\s+(\d+[a-z]?)/i);
-        if (match) phaseLabels.push(normalizePhaseLabel(match[2]));
-      }
-      for (const label of phaseLabels) {
-        const hasFile = phaseArtifacts.some((artifact) => normalizePhaseLabel(artifact.phasePrefix) === label);
-        if (!hasFile) {
-          warnings.push({ id: 'W4', severity: 'WARN', message: `ROADMAP.md references active Phase ${label} but no files found in .planning/phases/`, fix: 'Create missing phase dirs or update ROADMAP' });
-        }
+      for (const phase of lifecycle.phases.filter((entry) => entry.status !== 'not_started' && !entry.hasArtifacts)) {
+        warnings.push({
+          id: 'W4',
+          severity: 'WARN',
+          message: `ROADMAP.md references active Phase ${phase.number} but no files found in .planning/phases/`,
+          fix: 'Create missing phase dirs or update ROADMAP',
+        });
       }
     }
 
     // W5: Phase dir has PLAN but no SUMMARY (stale in-progress)
-    if (phaseArtifacts.length > 0) {
-      const plans = phaseArtifacts.filter((artifact) => artifact.name.includes('PLAN'));
-      for (const plan of plans) {
-        const prefix = plan.name.split('-PLAN')[0];
-        const hasSummary = phaseArtifacts.some((artifact) =>
-          artifact.dir === plan.dir &&
-          artifact.name.startsWith(prefix) &&
-          artifact.name.includes('SUMMARY')
-        );
-        if (!hasSummary) {
-          warnings.push({ id: 'W5', severity: 'WARN', message: `${plan.displayPath} exists but no matching SUMMARY found (stale in-progress?)`, fix: 'Resume or complete the phase' });
-        }
+    if (lifecycle.incompletePlans.length > 0) {
+      for (const plan of lifecycle.incompletePlans) {
+        warnings.push({
+          id: 'W5',
+          severity: 'WARN',
+          message: `${plan.displayPath} exists but no matching SUMMARY found (stale in-progress?)`,
+          fix: 'Resume or complete the phase',
+        });
       }
     }
 
@@ -202,7 +189,11 @@ export function createCmdHealth(ctx) {
       warnings.push({ id: 'W6', severity: 'WARN', message: 'No adapter surfaces detected', fix: 'Run `gsdd init --tools <platform>`' });
     }
 
-    warnings.push(...runTruthChecks(planningDir, cwd, healthCheckIds));
+    const runtimeFreshnessReport = configOk && Array.isArray(ctx.workflows)
+      ? evaluateRuntimeFreshness({ cwd, workflows: ctx.workflows })
+      : null;
+
+    warnings.push(...runTruthChecks(planningDir, cwd, healthCheckIds, { runtimeFreshnessReport }));
 
     // --- INFO checks ---
 
@@ -212,20 +203,12 @@ export function createCmdHealth(ctx) {
     }
 
     // I2: Phase completion count
-    if (roadmap) {
-      const lines = roadmap.split('\n');
-      let total = 0;
-      let done = 0;
-      for (const line of lines) {
-        const match = line.match(/^\s*[-*]\s*\[([x ]|-)\]\s*\*\*Phase\s+\d+/i);
-        if (match) {
-          total++;
-          if (match[1] === 'x') done++;
-        }
-      }
-      if (total > 0) {
-        info.push({ id: 'I2', severity: 'INFO', message: `Phases: ${done}/${total} completed` });
-      }
+    if (lifecycle.counts.total > 0) {
+      info.push({
+        id: 'I2',
+        severity: 'INFO',
+        message: `Phases: ${lifecycle.counts.completed}/${lifecycle.counts.total} completed`,
+      });
     }
 
     // I3: Which adapters are installed
@@ -268,34 +251,3 @@ function isFrameworkSourceRepo(cwd) {
   return existsSync(join(cwd, 'distilled', 'templates')) && existsSync(join(cwd, 'distilled', 'workflows'));
 }
 
-function normalizePhaseLabel(value) {
-  if (!value) return null;
-  return value.toLowerCase().replace(/^0+(\d)/, '$1');
-}
-
-function listPhaseArtifacts(phasesDir) {
-  const artifacts = [];
-  for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
-    const entryPath = join(phasesDir, entry.name);
-    if (entry.isFile()) {
-      artifacts.push(createPhaseArtifact('', entry.name));
-      continue;
-    }
-    if (!entry.isDirectory()) continue;
-    for (const child of readdirSync(entryPath, { withFileTypes: true })) {
-      if (child.isFile()) {
-        artifacts.push(createPhaseArtifact(entry.name, child.name));
-      }
-    }
-  }
-  return artifacts;
-}
-
-function createPhaseArtifact(dir, name) {
-  return {
-    dir,
-    name,
-    displayPath: dir ? `${dir}/${name}` : name,
-    phasePrefix: name.match(/^(\d+[a-z]?(?:\.\d+)?)-/i)?.[1] || dir.match(/^(\d+[a-z]?(?:\.\d+)?)-/i)?.[1] || null,
-  };
-}

package/bin/lib/init-runtime.mjs

@@ -2,37 +2,37 @@ const RUNTIME_OPTIONS = [
   {
     id: 'claude',
     label: 'Claude Code',
-    description: 'Directly validated native skills, commands, and agents',
+    description: 'Directly validated native skills, commands, and agents with local freshness checks',
     kind: 'native',
   },
   {
     id: 'opencode',
     label: 'OpenCode',
-    description: 'Directly validated native slash commands and agents',
+    description: 'Directly validated native slash commands and agents with local freshness checks',
     kind: 'native',
   },
   {
     id: 'codex',
     label: 'Codex CLI',
-    description: 'Directly validated portable skills plus native checker agents',
+    description: 'Directly validated portable skills plus native checker agents with local freshness checks',
     kind: 'native',
   },
   {
     id: 'cursor',
     label: 'Cursor',
-    description: 'Qualified support via skills-native slash commands from .agents/skills/',
+    description: 'Qualified support via skills-native slash commands from .agents/skills/ with the same local freshness checks',
     kind: 'skills_native',
   },
   {
     id: 'copilot',
     label: 'GitHub Copilot',
-    description: 'Qualified support via skills-native slash commands from .agents/skills/',
+    description: 'Qualified support via skills-native slash commands from .agents/skills/ with the same local freshness checks',
     kind: 'skills_native',
   },
   {
     id: 'gemini',
     label: 'Gemini CLI',
-    description: 'Qualified support via skills-native slash commands from .agents/skills/',
+    description: 'Qualified support via skills-native slash commands from .agents/skills/ with the same local freshness checks',
     kind: 'skills_native',
   },
 ];
@@ -161,25 +161,31 @@ export function getPostInitRoutingLines(selectedRuntimes) {
 
 export function getHelpText() {
   return `
-gsdd - GSD Distilled CLI
-Spec-Driven Development for AI coding agents.
+gsdd - Workspine CLI
+Portable multi-runtime software delivery framework for AI coding agents.
 
 Usage: gsdd <command> [args]
 
-Commands:
-  init [--tools <platform>] [--auto] [--brief <file>]
-                              Launch guided install wizard in TTYs, or use --tools for manual/headless setup
-                              --auto: non-interactive mode with smart defaults (requires --tools)
-                              --brief <file>: copy project brief to .planning/PROJECT_BRIEF.md
+Commands:
+  init [--tools <platform>] [--auto] [--brief <file>]
+                              Launch guided install wizard in TTYs, or use --tools for manual/headless setup
+                              --auto: non-interactive mode with smart defaults (requires --tools)
+                              --brief <file>: copy project brief to .planning/PROJECT_BRIEF.md
   update [--tools <platform>] [--templates] [--dry]
                               Regenerate adapters from latest framework sources
                               --templates: also refresh .planning/templates/ and roles
                               --dry: preview changes without writing files
-  health [--json]             Check workspace integrity (healthy/degraded/broken)
-  models [subcommand]         Inspect or update model profile / runtime overrides
-  find-phase [N]              Show phase info as JSON (for agent consumption)
-  verify <N>                  Run artifact checks for phase N
-  scaffold phase <N> [name]   Create a new phase plan file
+  health [--json]             Check workspace integrity (healthy/degraded/broken)
+  models [subcommand]         Inspect or update model profile / runtime overrides
+  find-phase [N]              Show phase info as JSON (for agent consumption)
+  verify <N>                  Run artifact checks for phase N
+  scaffold phase <N> [name]   Create a new phase plan file
+  file-op <copy|delete|regex-sub>
+                              Run deterministic workspace-confined file copy/delete/text mutation
+  phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])
+  lifecycle-preflight <surface> [phase]
+                              Inspect deterministic lifecycle gate results for a workflow surface
+  help                        Show this summary
 
 Platforms (for --tools):
   claude    Generate Claude Code skills (.claude/skills/gsdd-*), commands (.claude/commands/gsdd-*.md), and native agents (.claude/agents/gsdd-*.md)
@@ -193,12 +199,14 @@ Platforms (for --tools):
 
 Notes:
   - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
+  - Workspine is the public product name; the retained package, command, workflow, and workspace contracts stay gsdd-cli, gsdd, gsdd-*, and .planning/
   - running plain \`gsdd init\` in a terminal opens the guided runtime-selection wizard
   - the wizard lets you pick runtimes first, then separately decide whether repo-wide AGENTS.md governance is worth installing
+  - \`gsdd health\` compares any installed generated runtime surfaces against current render output and points back to \`gsdd update\` when they drift
   - directly validated launch surfaces in this repo are Claude Code, OpenCode, and Codex CLI
   - Cursor, Copilot, and Gemini are qualified support through the shared .agents/skills/ surface plus optional governance
   - --tools remains the advanced/manual path and preserves legacy runtime aliases for backward compatibility
-  - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface)
+  - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface; $gsdd-plan is plan-only until explicit $gsdd-execute)
   - root AGENTS.md is only written on init when explicitly requested via --tools agents, --tools all, or the wizard governance opt-in
 
 Examples:
@@ -219,8 +227,20 @@ Examples:
   npx gsdd-cli verify 1
   npx gsdd-cli scaffold phase 4 Payments
 
-Workflows (run via skills/adapters generated by init, not direct CLI):
-  map-codebase      Map or refresh codebase (.agents/skills/gsdd-map-codebase/)
-  audit-milestone   Audit a completed milestone (.agents/skills/gsdd-audit-milestone/)
-`;
-}
+Workflows (run via skills/adapters generated by init, not direct CLI):
+  gsdd-new-project          Full initializer: questioning, brownfield audit, research, spec, roadmap
+  gsdd-map-codebase         Map or refresh brownfield codebase context
+  gsdd-plan                 Research, plan, and fresh-context plan check for a phase
+  gsdd-execute              Execute a phase plan and write phase summaries
+  gsdd-verify               Verify a completed phase with 3-level checks
+  gsdd-verify-work          Conversational UAT validation for user-facing behavior
+  gsdd-audit-milestone      Cross-phase integration, requirements coverage, and E2E audit
+  gsdd-complete-milestone   Archive a shipped milestone and collapse roadmap state
+  gsdd-new-milestone        Start the next milestone with goals, requirements, and phases
+  gsdd-plan-milestone-gaps  Turn milestone-audit gaps into closure phases
+  gsdd-quick                Bounded brownfield lane for sub-hour work
+  gsdd-pause                Save session context to checkpoint
+  gsdd-resume               Restore context and route to the next action
+  gsdd-progress             Read-only status and routing surface
+`;
+}

package/bin/lib/init.mjs

@@ -4,13 +4,9 @@ import { createCmdInit, createCmdUpdate } from './init-flow.mjs';
 import { createInitPromptApi, promptChoiceList } from './init-prompts.mjs';
 import { buildRuntimeChoices, detectPlatforms, getHelpText, normalizeRequestedTools } from './init-runtime.mjs';
 
-function cmdHelp() {
-  console.log(`${getHelpText().trimEnd()}
-  file-op <copy|delete|regex-sub>
-                              Run deterministic workspace-confined file copy/delete/text mutation
-  phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])
-`);
-}
+function cmdHelp() {
+  console.log(getHelpText().trimEnd());
+}
 
 export {
   buildRuntimeChoices,

package/bin/lib/lifecycle-preflight.mjs

@@ -0,0 +1,333 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { output } from './cli-utils.mjs';
+import { describeEvidenceSurface } from './evidence-contract.mjs';
+import { evaluateLifecycleState, normalizePhaseToken } from './lifecycle-state.mjs';
+import { checkDrift } from './session-fingerprint.mjs';
+
+const SURFACE_POLICIES = {
+  progress: {
+    classification: 'read_only',
+    ownedWrites: [],
+    explicitLifecycleMutation: 'none',
+  },
+  execute: {
+    classification: 'owned_write',
+    ownedWrites: ['summary'],
+    explicitLifecycleMutation: 'phase-status',
+    phaseRequired: true,
+  },
+  verify: {
+    classification: 'owned_write',
+    ownedWrites: ['verification'],
+    explicitLifecycleMutation: 'phase-status',
+    phaseRequired: true,
+  },
+  'audit-milestone': {
+    classification: 'owned_write',
+    ownedWrites: ['milestone-audit'],
+    explicitLifecycleMutation: 'none',
+  },
+  'complete-milestone': {
+    classification: 'owned_write',
+    ownedWrites: ['milestone-archives', 'milestones-ledger', 'spec', 'roadmap'],
+    explicitLifecycleMutation: 'none',
+  },
+  'new-milestone': {
+    classification: 'owned_write',
+    ownedWrites: ['spec', 'roadmap', 'phase-directories'],
+    explicitLifecycleMutation: 'none',
+  },
+  resume: {
+    classification: 'owned_write',
+    ownedWrites: ['checkpoint-cleanup'],
+    explicitLifecycleMutation: 'none',
+  },
+};
+
+export function evaluateLifecyclePreflight({
+  planningDir,
+  surface,
+  phaseNumber = null,
+  expectsMutation = 'none',
+} = {}) {
+  if (!planningDir) {
+    throw new Error('planningDir is required');
+  }
+
+  const policy = SURFACE_POLICIES[surface];
+  if (!policy) {
+    throw new Error(`Unsupported lifecycle surface: ${surface}`);
+  }
+
+  const lifecycle = evaluateLifecycleState({ planningDir });
+  const normalizedPhase = phaseNumber ? normalizePhaseToken(phaseNumber) : null;
+  const checkpointPath = join(planningDir, '.continue-here.md');
+  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/']));
+  }
+
+  if (expectsMutation !== 'none' && expectsMutation !== policy.explicitLifecycleMutation) {
+    blockers.push(
+      blocker(
+        'illegal_lifecycle_mutation',
+        `${surface} is classified as ${policy.classification} and cannot mutate lifecycle state via ${expectsMutation}.`,
+        []
+      )
+    );
+  }
+
+  if (policy.phaseRequired && !normalizedPhase) {
+    blockers.push(blocker('missing_phase_argument', `${surface} requires an explicit phase number.`, []));
+  }
+
+  if (normalizedPhase) {
+    blockers.push(...buildPhaseBlockers({ lifecycle, phaseToken: normalizedPhase, surface }));
+  }
+
+  if (surface === 'audit-milestone') {
+    blockers.push(...buildAuditBlockers(lifecycle));
+  }
+
+  if (surface === 'complete-milestone') {
+    blockers.push(...buildAuditBlockers(lifecycle, { allowArchivedBlocker: true }));
+    blockers.push(...buildCompletionBlockers(planningDir, lifecycle));
+  }
+
+  if (surface === 'new-milestone') {
+    if (!existsSync(specPath)) {
+      blockers.push(blocker('missing_spec', 'SPEC.md is required before starting a new milestone.', ['.planning/SPEC.md']));
+    }
+    if (!existsSync(milestonesPath)) {
+      blockers.push(blocker('missing_milestones', 'MILESTONES.md is required before starting a new milestone.', ['.planning/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']
+        )
+      );
+    }
+  }
+
+  if (surface === 'resume' && !existsSync(checkpointPath)) {
+    blockers.push(blocker('missing_checkpoint', 'resume requires .planning/.continue-here.md to exist.', ['.planning/.continue-here.md']));
+  }
+
+  const warnings = [];
+
+  if (existsSync(planningDir)) {
+    const drift = checkDrift(planningDir);
+    if (drift.drifted) {
+      warnings.push({
+        code: 'planning_state_drift',
+        message: `Planning state has drifted since the last recorded session: ${drift.details.join('; ')}`,
+        artifacts: ['.planning/ROADMAP.md', '.planning/SPEC.md', '.planning/config.json'],
+      });
+    }
+  }
+
+  return {
+    surface,
+    phase: normalizedPhase,
+    classification: policy.classification,
+    ownedWrites: policy.ownedWrites,
+    explicitLifecycleMutation: policy.explicitLifecycleMutation,
+    closureEvidence: describeEvidenceSurface(surface),
+    mutationRequest: expectsMutation,
+    allowed: blockers.length === 0,
+    status: blockers.length === 0 ? 'allowed' : 'blocked',
+    reason: blockers[0]?.code ?? null,
+    blockers,
+    warnings,
+    lifecycle: {
+      currentMilestone: lifecycle.currentMilestone,
+      currentPhase: lifecycle.currentPhase ? lifecycle.currentPhase.number : null,
+      nextPhase: lifecycle.nextPhase ? lifecycle.nextPhase.number : null,
+      counts: lifecycle.counts,
+    },
+  };
+}
+
+function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
+  const blockers = [];
+  const phaseEntry = lifecycle.phases.find((phase) => phase.number === phaseToken);
+  if (!phaseEntry) {
+    blockers.push(
+      blocker(
+        'missing_phase',
+        `Phase ${phaseToken} was not found in the active roadmap.`,
+        ['.planning/ROADMAP.md']
+      )
+    );
+    return blockers;
+  }
+
+  const planArtifacts = lifecycle.phaseArtifacts.filter((artifact) => artifact.phaseToken === phaseToken && artifact.kind === 'plan');
+  const summaryArtifacts = lifecycle.phaseArtifacts.filter((artifact) => artifact.phaseToken === phaseToken && artifact.kind === 'summary');
+  const pendingPlans = planArtifacts.filter(
+    (artifact) => !summaryArtifacts.some((candidate) => candidate.dir === artifact.dir && candidate.baseId === artifact.baseId)
+  );
+
+  if (surface === 'execute') {
+    if (planArtifacts.length === 0) {
+      blockers.push(
+        blocker(
+          'missing_plan',
+          `Phase ${phaseToken} cannot execute because no PLAN artifact exists.`,
+          ['.planning/phases/']
+        )
+      );
+    } else if (pendingPlans.length === 0) {
+      blockers.push(
+        blocker(
+          'no_pending_plan',
+          `Phase ${phaseToken} has no pending PLAN artifacts left to execute.`,
+          planArtifacts.map((artifact) => artifact.displayPath)
+        )
+      );
+    }
+  }
+
+  if (surface === 'verify') {
+    if (planArtifacts.length === 0) {
+      blockers.push(
+        blocker(
+          'missing_plan',
+          `Phase ${phaseToken} cannot be verified because no PLAN artifact exists.`,
+          ['.planning/phases/']
+        )
+      );
+    }
+    if (summaryArtifacts.length === 0) {
+      blockers.push(
+        blocker(
+          'missing_summary',
+          `Phase ${phaseToken} cannot be verified because no SUMMARY artifact exists yet.`,
+          ['.planning/phases/']
+        )
+      );
+    }
+  }
+
+  return blockers;
+}
+
+function buildAuditBlockers(lifecycle, { allowArchivedBlocker = false } = {}) {
+  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']));
+    return blockers;
+  }
+
+  if (lifecycle.currentMilestone.archiveState === 'archived') {
+    blockers.push(
+      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']
+      )
+    );
+  }
+
+  if (lifecycle.counts.total === 0) {
+    blockers.push(blocker('missing_phases', 'No active milestone phases were found in ROADMAP.md.', ['.planning/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']
+      )
+    );
+  }
+
+  const phasesMissingVerification = lifecycle.phases
+    .filter((phase) => phase.status === 'done')
+    .filter((phase) => !phase.artifacts.some((artifact) => artifact.kind === 'verification'))
+    .map((phase) => phase.number);
+
+  if (phasesMissingVerification.length > 0) {
+    blockers.push(
+      blocker(
+        'missing_verification',
+        `Completed phases are missing VERIFICATION artifacts (${phasesMissingVerification.join(', ')}).`,
+        ['.planning/phases/']
+      )
+    );
+  }
+
+  return blockers;
+}
+
+function buildCompletionBlockers(planningDir, lifecycle) {
+  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]
+      ),
+    ];
+  }
+
+  const auditContent = readFileSync(auditPath, 'utf-8');
+  const statusMatch = auditContent.match(/^status:\s*(.+)$/m);
+  if (!statusMatch || statusMatch[1].trim() !== 'passed') {
+    return [
+      blocker(
+        'audit_not_passed',
+        `Milestone ${lifecycle.currentMilestone.version} requires a passed audit before completion.`,
+        [auditPath]
+      ),
+    ];
+  }
+
+  return [];
+}
+
+function blocker(code, message, artifacts) {
+  return { code, message, artifacts };
+}
+
+export function cmdLifecyclePreflight(...args) {
+  const cwd = process.cwd();
+  const planningDir = join(cwd, '.planning');
+  const [surface, maybePhase, ...rest] = args;
+
+  if (!surface) {
+    console.error('Usage: gsdd lifecycle-preflight <surface> [phase] [--expects-mutation <none|phase-status>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  let phaseNumber = maybePhase && !maybePhase.startsWith('--') ? maybePhase : null;
+  let expectsMutation = 'none';
+
+  const flagArgs = phaseNumber ? rest : [maybePhase, ...rest].filter(Boolean);
+  for (let index = 0; index < flagArgs.length; index += 1) {
+    const arg = flagArgs[index];
+    if (arg === '--expects-mutation') {
+      expectsMutation = flagArgs[index + 1] ?? 'none';
+      index += 1;
+    }
+  }
+
+  try {
+    const result = evaluateLifecyclePreflight({ planningDir, surface, phaseNumber, expectsMutation });
+    output(result);
+    if (!result.allowed) {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}