gsdd-cli 0.16.1 → 0.18.1

package/bin/lib/health-truth.mjs

@@ -1,9 +1,15 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import {
+  getRuntimeFreshnessRepairGuidance,
+  summarizeRuntimeFreshnessIssues,
+} from './runtime-freshness.mjs';
+import { checkDrift } from './session-fingerprint.mjs';
 
-export const TRUTH_CHECK_IDS = ['W7', 'W8', 'W9', 'W10'];
+export const TRUTH_CHECK_IDS = ['W7', 'W8', 'W9', 'W10', 'W11', 'W12'];
 
-export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
+export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, options = {}) {
   const warnings = [];
   const designPath = join(frameworkDir, 'distilled', 'DESIGN.md');
   const readmePath = join(frameworkDir, 'distilled', 'README.md');
@@ -11,6 +17,7 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
   const gapsPath = join(frameworkDir, '.internal-research', 'gaps.md');
   const specPath = join(planningDir, 'SPEC.md');
   const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const lifecycle = evaluateLifecycleState({ planningDir });
 
   if (existsSync(designPath)) {
     const documentedIds = extractHealthTableIds(readFileSync(designPath, 'utf-8'));
@@ -69,16 +76,7 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
   }
 
   if (existsSync(specPath) && existsSync(roadmapPath)) {
-    const spec = readFileSync(specPath, 'utf-8');
-    const roadmap = readFileSync(roadmapPath, 'utf-8');
-    const checkedRequirements = extractCheckedRequirements(spec);
-    const roadmapRequirements = extractRoadmapRequirements(roadmap);
-    const mismatches = [];
-    for (const [requirementId, roadmapStatus] of roadmapRequirements.entries()) {
-      const specChecked = checkedRequirements.has(requirementId);
-      if (roadmapStatus && !specChecked) mismatches.push(`${requirementId} phase complete but SPEC unchecked`);
-      if (!roadmapStatus && specChecked) mismatches.push(`${requirementId} SPEC checked but phase incomplete`);
-    }
+    const mismatches = lifecycle.requirementAlignment.mismatches;
     if (mismatches.length > 0) {
       warnings.push({
         id: 'W10',
@@ -89,6 +87,25 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
     }
   }
 
+  if (options.runtimeFreshnessReport?.issueCount > 0) {
+    warnings.push({
+      id: 'W11',
+      severity: 'WARN',
+      message: `Installed generated runtime and workflow-helper surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
+      fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
+    });
+  }
+
+  const drift = checkDrift(planningDir);
+  if (drift.drifted) {
+    warnings.push({
+      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',
+    });
+  }
+
   return warnings;
 }
 
@@ -167,22 +184,3 @@ function extractSection(content, startMarker, endMarker) {
 function normalizeContent(content) {
   return content.replace(/\r\n/g, '\n');
 }
-
-function extractCheckedRequirements(content) {
-  const checked = new Set();
-  for (const result of content.matchAll(/- \[x\] \*\*\[([A-Z0-9-]+)]\*\*/g)) {
-    checked.add(result[1]);
-  }
-  return checked;
-}
-
-function extractRoadmapRequirements(content) {
-  const mapped = new Map();
-  for (const result of content.matchAll(/- \[([ x-])] \*\*Phase\s+\d+[a-z]?:.*?\*\*\s+—\s+\[([^\]]+)]/g)) {
-    const requirementIds = result[2].split(',').map((id) => id.trim());
-    for (const requirementId of requirementIds) {
-      mapped.set(requirementId, result[1].toLowerCase() === 'x');
-    }
-  }
-  return mapped;
-}

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) {
@@ -19,7 +21,7 @@ export function createCmdHealth(ctx) {
     const cwd = process.cwd();
     const planningDir = join(cwd, '.planning');
     const frameworkSourceMode = isFrameworkSourceRepo(cwd);
-    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
+    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
@@ -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) {
@@ -53,8 +57,10 @@ export function createCmdHealth(ctx) {
     }
 
     // E3: templates/ missing
-    const templatesDir = join(planningDir, 'templates');
-    const hasTemplatesDir = existsSync(templatesDir);
+    const templatesDir = join(planningDir, 'templates');
+    const runtimeHelpersDir = join(planningDir, 'bin');
+    const hasTemplatesDir = existsSync(templatesDir);
+    const hasRuntimeHelpersDir = existsSync(runtimeHelpersDir);
     const rolesDir = join(templatesDir, 'roles');
     const delegatesDir = join(templatesDir, 'delegates');
     const hasRolesDir = hasTemplatesDir && existsSync(rolesDir);
@@ -117,76 +123,60 @@ export function createCmdHealth(ctx) {
     // --- WARNING checks ---
 
     // W1: generation-manifest.json missing
-    const manifest = skipInstalledTemplateChecks ? null : readManifest(planningDir);
-    if (!manifest && !skipInstalledTemplateChecks) {
-      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update --templates` to create' });
-    }
+    const manifest = skipInstalledTemplateChecks ? null : readManifest(planningDir);
+    if (!manifest && !skipInstalledTemplateChecks) {
+      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update` to create' });
+    }
 
     // W2 + W3: template/role hash mismatches and missing files
     if (manifest && hasTemplatesDir) {
-      const allCategories = [
-        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null },
-        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research },
-        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase },
-        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root },
-        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null },
-      ];
-
-      for (const cat of allCategories) {
-        if (!cat.hashes) continue;
-        const result = detectModifications(cat.dir, cat.hashes);
-        if (result.modified.length > 0) {
-          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: 'Intentional? Run `gsdd update --templates` to reset' });
-        }
-        if (result.missing.length > 0) {
-          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: 'Run `gsdd update --templates` to restore' });
-        }
-      }
-    }
+      const allCategories = [
+        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null, fixCommand: 'gsdd update --templates' },
+        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research, fixCommand: 'gsdd update --templates' },
+        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase, fixCommand: 'gsdd update --templates' },
+        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root, fixCommand: 'gsdd update --templates' },
+        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null, fixCommand: 'gsdd update --templates' },
+        { name: 'runtime helpers', dir: planningDir, hashes: hasRuntimeHelpersDir ? manifest.runtimeHelpers : null, fixCommand: 'gsdd update' },
+      ];
+
+      for (const cat of allCategories) {
+        if (!cat.hashes) continue;
+        const result = detectModifications(cat.dir, cat.hashes);
+        if (result.modified.length > 0) {
+          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: `Intentional? Run \`${cat.fixCommand}\` to reset` });
+        }
+        if (result.missing.length > 0) {
+          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: `Run \`${cat.fixCommand}\` to restore` });
+        }
+      }
+    }
 
     // W4: ROADMAP.md references phases not found in .planning/phases/
     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 +192,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 +206,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 +254,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-flow.mjs

@@ -1,7 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
-import { join, isAbsolute } from 'path';
-import { renderSkillContent } from './rendering.mjs';
-import { buildManifest, writeManifest } from './manifest.mjs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
+import { join, isAbsolute } from 'path';
+import { renderPlanningCliLauncher, renderSkillContent } from './rendering.mjs';
+import { buildManifest, readManifest, writeManifest } from './manifest.mjs';
 import { parseFlagValue, parseToolsFlag, parseAutoFlag } from './cli-utils.mjs';
 import { buildDefaultConfig, COST_PROFILES, RIGOR_PROFILES } from './models.mjs';
 import { installProjectTemplates, refreshTemplates } from './templates.mjs';
@@ -106,8 +106,11 @@ export function createCmdInit(ctx) {
       console.log('  - copied project brief to .planning/PROJECT_BRIEF.md');
     }
 
-    generateOpenStandardSkills(ctx.cwd, ctx.workflows);
-    console.log('  - generated open-standard skills (.agents/skills/gsdd-*)');
+    generateOpenStandardSkills(ctx.cwd, ctx.workflows);
+    console.log('  - generated open-standard skills (.agents/skills/gsdd-*)');
+
+    generatePlanningCliLauncher(ctx);
+    console.log('  - generated local workflow helper (.planning/bin/gsdd.mjs)');
 
     for (const adapter of resolveAdapters(ctx.adapters, interactiveSession.adapterTargets)) {
       adapter.generate();
@@ -144,15 +147,25 @@ export function createCmdUpdate(ctx) {
       updated = true;
     }
 
-    if (platforms.length > 0 || existsSync(join(ctx.cwd, '.agents', 'skills'))) {
-      if (isDry) {
-        console.log('  - would update open-standard skills (.agents/skills/gsdd-*)');
-      } else {
-        generateOpenStandardSkills(ctx.cwd, ctx.workflows);
+    if (platforms.length > 0 || existsSync(join(ctx.cwd, '.agents', 'skills'))) {
+      if (isDry) {
+        console.log('  - would update open-standard skills (.agents/skills/gsdd-*)');
+      } else {
+        generateOpenStandardSkills(ctx.cwd, ctx.workflows);
         console.log('  - updated open-standard skills (.agents/skills/gsdd-*)');
-      }
-      updated = true;
-    }
+      }
+      updated = true;
+    }
+
+    if (existsSync(ctx.planningDir)) {
+      if (isDry) {
+        console.log('  - would update local workflow helper (.planning/bin/gsdd.mjs)');
+      } else {
+        generatePlanningCliLauncher(ctx);
+        console.log('  - updated local workflow helper (.planning/bin/gsdd.mjs)');
+      }
+      updated = true;
+    }
 
     for (const adapter of getAdaptersToUpdate(ctx.adapters, platforms)) {
       if (isDry) {
@@ -167,26 +180,70 @@ export function createCmdUpdate(ctx) {
 
     if (!updated) {
       console.log('  - no adapters found to update (run `gsdd init` first)');
-    } else if (isDry) {
-      console.log('\nDry run complete. No files were written.\n');
-    } else {
-      if (doTemplates && existsSync(ctx.planningDir)) {
-        const manifest = buildManifest({ planningDir: ctx.planningDir, frameworkVersion: ctx.frameworkVersion });
-        writeManifest(ctx.planningDir, manifest);
-        console.log('  - updated generation manifest');
-      }
-      console.log('\nAdapters updated.\n');
-    }
-  };
-}
-
-function generateOpenStandardSkills(cwd, workflows) {
-  for (const workflow of workflows) {
-    const dir = join(cwd, '.agents', 'skills', workflow.name);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'SKILL.md'), renderSkillContent(workflow));
-  }
-}
+    } else if (isDry) {
+      console.log('\nDry run complete. No files were written.\n');
+    } else {
+      if (existsSync(ctx.planningDir)) {
+        const manifest = buildUpdateManifest({
+          planningDir: ctx.planningDir,
+          frameworkVersion: ctx.frameworkVersion,
+          updateTemplates: doTemplates,
+        });
+        if (manifest) {
+          writeManifest(ctx.planningDir, manifest);
+          console.log('  - updated generation manifest');
+        }
+      }
+      console.log('\nAdapters updated.\n');
+    }
+  };
+}
+
+function generateOpenStandardSkills(cwd, workflows) {
+  for (const workflow of workflows) {
+    const dir = join(cwd, '.agents', 'skills', workflow.name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'SKILL.md'), renderSkillContent(workflow));
+  }
+}
+
+function generatePlanningCliLauncher(ctx) {
+  const dir = join(ctx.planningDir, 'bin');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, 'gsdd.mjs'),
+    renderPlanningCliLauncher({
+      packageName: ctx.packageName,
+      packageVersion: ctx.packageVersion,
+    })
+  );
+}
+
+function buildUpdateManifest({ planningDir, frameworkVersion, updateTemplates }) {
+  const existingManifest = readManifest(planningDir);
+  const nextManifest = buildManifest({ planningDir, frameworkVersion });
+
+  if (existingManifest && !updateTemplates) {
+    nextManifest.templates = existingManifest.templates ?? nextManifest.templates;
+    nextManifest.roles = existingManifest.roles ?? nextManifest.roles;
+  }
+
+  if (existingManifest && manifestsEqualIgnoringTimestamp(existingManifest, nextManifest)) {
+    return null;
+  }
+
+  return nextManifest;
+}
+
+function manifestsEqualIgnoringTimestamp(left, right) {
+  return JSON.stringify(stripManifestTimestamp(left)) === JSON.stringify(stripManifestTimestamp(right));
+}
+
+function stripManifestTimestamp(manifest) {
+  if (!manifest || typeof manifest !== 'object') return manifest;
+  const { generatedAt, ...rest } = manifest;
+  return rest;
+}
 
 async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedConfig = null }) {
   const configFile = join(planningDir, 'config.json');

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
+Repo-native delivery spine for long-horizon AI-assisted work across coding runtimes.
 
 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)
@@ -192,13 +198,16 @@ Platforms (for --tools):
   all       Generate all adapters (Claude, OpenCode, Codex, AGENTS.md, Cursor, Copilot, Gemini)
 
 Notes:
-  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
+  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
+  - init also generates .planning/bin/gsdd.mjs so workflow-embedded helper commands do not depend on a global gsdd binary
+  - 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 +228,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,