gsdd-cli 0.16.1 → 0.18.0

package/bin/lib/lifecycle-state.mjs

@@ -0,0 +1,293 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const PHASE_LINE_RE = /^\s*[-*]\s*\[([ x-])\]\s*\*\*Phase\s+(\d+(?:\.\d+)*[a-z]?):\s*(.+?)\*\*(?:\s+—\s+\[([^\]]+)])?/i;
+const ACTIVE_MILESTONE_HEADING_RE = /^###\s+(v[^\s]+)\s+(.+)$/im;
+const MILESTONE_LEDGER_HEADING_RE = /^##\s+(?:✅\s+)?(v[^\s]+)\s*(?:—|-)?\s*(.*)$/i;
+
+export function evaluateLifecycleState({ planningDir, provenance = null } = {}) {
+  if (!planningDir) {
+    throw new Error('planningDir is required');
+  }
+
+  const specPath = join(planningDir, 'SPEC.md');
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const milestonesPath = join(planningDir, 'MILESTONES.md');
+  const phasesDir = join(planningDir, 'phases');
+
+  const spec = readTextIfExists(specPath);
+  const roadmap = readTextIfExists(roadmapPath);
+  const milestones = readTextIfExists(milestonesPath);
+
+  const phases = parseActiveRoadmapPhases(roadmap);
+  const phaseArtifacts = collectPhaseArtifacts(phasesDir);
+  const enrichedPhases = phases.map((phase) => {
+    const matchingArtifacts = phaseArtifacts.filter((artifact) => artifact.phaseToken === phase.number);
+    const hasPlan = matchingArtifacts.some((artifact) => artifact.kind === 'plan');
+    const hasSummary = matchingArtifacts.some((artifact) => artifact.kind === 'summary');
+    return {
+      ...phase,
+      hasArtifacts: matchingArtifacts.length > 0,
+      hasPlan,
+      hasSummary,
+      artifacts: matchingArtifacts,
+    };
+  });
+
+  const incompletePlans = phaseArtifacts.filter((artifact) => {
+    if (artifact.kind !== 'plan') return false;
+    return !phaseArtifacts.some((candidate) =>
+      candidate.dir === artifact.dir &&
+      candidate.baseId === artifact.baseId &&
+      candidate.kind === 'summary'
+    );
+  });
+
+  const counts = {
+    total: enrichedPhases.length,
+    completed: enrichedPhases.filter((phase) => phase.status === 'done').length,
+    inProgress: enrichedPhases.filter((phase) => phase.status === 'in_progress').length,
+    notStarted: enrichedPhases.filter((phase) => phase.status === 'not_started').length,
+  };
+
+  const milestoneLedger = parseMilestoneLedger(milestones);
+  const currentMilestone = deriveCurrentMilestone({
+    roadmap,
+    planningDir,
+    milestoneLedger,
+    counts,
+  });
+
+  return {
+    paths: {
+      specPath,
+      roadmapPath,
+      milestonesPath,
+      phasesDir,
+    },
+    currentMilestone,
+    phases: enrichedPhases,
+    currentPhase: enrichedPhases.find((phase) => phase.status === 'in_progress') || null,
+    nextPhase: enrichedPhases.find((phase) => phase.status === 'not_started') || null,
+    counts,
+    phaseArtifacts,
+    incompletePlans,
+    requirementAlignment: evaluateRequirementAlignment(spec, enrichedPhases),
+    provenance: provenance
+      ? {
+          provided: true,
+          ...provenance,
+        }
+      : { provided: false },
+  };
+}
+
+function readTextIfExists(filePath) {
+  return existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+}
+
+function normalizeContent(content) {
+  return String(content || '').replace(/\r\n/g, '\n');
+}
+
+export function normalizePhaseToken(value) {
+  const raw = String(value || '').trim().toLowerCase();
+  const match = raw.match(/^(\d+(?:\.\d+)*)([a-z]?)$/i);
+  if (!match) return raw;
+
+  const numericSegments = match[1]
+    .split('.')
+    .map((segment) => String(parseInt(segment, 10)));
+  return `${numericSegments.join('.')}${match[2] || ''}`;
+}
+
+function normalizePhaseStatus(marker) {
+  const normalized = String(marker || '').trim().toLowerCase();
+  if (normalized === 'x') return 'done';
+  if (normalized === '-') return 'in_progress';
+  return 'not_started';
+}
+
+function parseActiveRoadmapPhases(roadmap) {
+  if (!roadmap) return [];
+
+  const phases = [];
+  let inDetails = false;
+
+  for (const line of normalizeContent(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(PHASE_LINE_RE);
+    if (!match) continue;
+
+    phases.push({
+      number: normalizePhaseToken(match[2]),
+      title: match[3].trim(),
+      status: normalizePhaseStatus(match[1]),
+      requirements: splitRequirementList(match[4]),
+    });
+  }
+
+  return phases;
+}
+
+function splitRequirementList(rawRequirements = '') {
+  return String(rawRequirements)
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function collectPhaseArtifacts(phasesDir) {
+  if (!existsSync(phasesDir)) return [];
+
+  const artifacts = [];
+  for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
+    const entryPath = join(phasesDir, entry.name);
+    if (entry.isFile()) {
+      const artifact = classifyPhaseArtifact('', entry.name);
+      if (artifact) artifacts.push(artifact);
+      continue;
+    }
+
+    if (!entry.isDirectory()) continue;
+
+    for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+      if (!child.isFile()) continue;
+      const artifact = classifyPhaseArtifact(entry.name, child.name);
+      if (artifact) artifacts.push(artifact);
+    }
+  }
+
+  return artifacts;
+}
+
+function classifyPhaseArtifact(dir, name) {
+  const baseIdMatch = name.match(/^(\d+(?:\.\d+)*[a-z]?(?:-\d+)?)/i);
+  const phaseTokenMatch = (dir ? dir.match(/^(\d+(?:\.\d+)*[a-z]?)-/i) : null)
+    || name.match(/^(\d+(?:\.\d+)*[a-z]?)/i);
+
+  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';
+
+  return {
+    dir,
+    name,
+    displayPath: dir ? `${dir}/${name}` : name,
+    baseId: baseIdMatch[1],
+    phaseToken: normalizePhaseToken(phaseTokenMatch[1]),
+    kind,
+  };
+}
+
+function parseMilestoneLedger(content) {
+  if (!content) return [];
+
+  const entries = [];
+  let current = null;
+
+  for (const line of normalizeContent(content).split('\n')) {
+    const headingMatch = line.match(MILESTONE_LEDGER_HEADING_RE);
+    if (headingMatch) {
+      if (current) entries.push(current);
+      current = {
+        version: headingMatch[1],
+        title: headingMatch[2].trim(),
+        lines: [],
+      };
+      continue;
+    }
+
+    if (current) {
+      current.lines.push(line);
+    }
+  }
+
+  if (current) entries.push(current);
+
+  return entries.map((entry) => {
+    const section = entry.lines.join('\n');
+    const statusMatch = section.match(/^- Status:\s*(.+)$/im);
+    const shipped = /(^- Status:\s*shipped$)|(^- Shipped:\s+)/im.test(section) || /^✅/.test(entry.title);
+    return {
+      version: entry.version,
+      title: entry.title.replace(/^✅\s*/, ''),
+      status: statusMatch ? statusMatch[1].trim().toLowerCase() : shipped ? 'shipped' : 'unknown',
+      shipped,
+    };
+  });
+}
+
+function deriveCurrentMilestone({ roadmap, planningDir, milestoneLedger, counts }) {
+  const normalizedRoadmap = normalizeContent(roadmap);
+  const headingMatch = normalizedRoadmap.match(ACTIVE_MILESTONE_HEADING_RE);
+  if (!headingMatch) {
+    return {
+      version: null,
+      title: null,
+      shippedInLedger: false,
+      hasMatchingAudit: false,
+      archiveState: 'unknown',
+      counts,
+    };
+  }
+
+  const version = headingMatch[1];
+  const title = headingMatch[2].trim();
+  const ledgerEntry = milestoneLedger.find((entry) => entry.version === version) || null;
+  const auditPath = join(planningDir, `${version}-MILESTONE-AUDIT.md`);
+  const hasMatchingAudit = existsSync(auditPath);
+  const shippedInLedger = Boolean(ledgerEntry?.shipped);
+
+  return {
+    version,
+    title,
+    shippedInLedger,
+    hasMatchingAudit,
+    archiveState: shippedInLedger && hasMatchingAudit ? 'archived' : 'active',
+    counts,
+  };
+}
+
+function evaluateRequirementAlignment(spec, phases) {
+  const checkedRequirements = new Set(
+    [...normalizeContent(spec).matchAll(/- \[x\] \*\*\[([A-Z0-9-]+)]\*\*/g)].map((result) => result[1])
+  );
+
+  const roadmapRequirements = new Map();
+  for (const phase of phases) {
+    for (const requirementId of phase.requirements) {
+      roadmapRequirements.set(requirementId, phase.status === 'done');
+    }
+  }
+
+  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`);
+    }
+  }
+
+  return {
+    checkedRequirements,
+    roadmapRequirements,
+    mismatches,
+  };
+}

package/bin/lib/phase.mjs

@@ -6,6 +6,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
 import { join, basename } from 'path';
 import { output } from './cli-utils.mjs';
+import { writeFingerprint } from './session-fingerprint.mjs';
 
 const PHASE_STATUS_MARKERS = {
   not_started: '[ ]',
@@ -27,7 +28,60 @@ const ROADMAP_PHASE_STATUS_RE = new RegExp(
 
 function findFiles(dir, prefix) {
   if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter((f) => f.startsWith(prefix) || f.startsWith(prefix.replace(/^0+/, '')));
+
+  const phaseArtifactPrefix = String(prefix).match(/^(\d+(?:\.\d+)*[a-z]?)-(PLAN|SUMMARY)$/i);
+  if (!phaseArtifactPrefix) {
+    return readdirSync(dir).filter((f) => f.startsWith(prefix) || f.startsWith(prefix.replace(/^0+/, '')));
+  }
+
+  const targetPhase = normalizePhaseToken(phaseArtifactPrefix[1]);
+  const targetKind = phaseArtifactPrefix[2].toUpperCase();
+
+  return listPhaseArtifacts(dir)
+    .filter((artifact) => artifact.phaseToken === targetPhase && artifact.kind === targetKind)
+    .map((artifact) => artifact.displayPath);
+}
+
+function listPhaseArtifacts(dir) {
+  if (!existsSync(dir)) return [];
+
+  const artifacts = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile()) {
+      const artifact = classifyPhaseArtifact('', entry.name);
+      if (artifact) artifacts.push(artifact);
+      continue;
+    }
+
+    if (!entry.isDirectory()) continue;
+
+    const entryPath = join(dir, entry.name);
+    for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+      if (!child.isFile()) continue;
+      const artifact = classifyPhaseArtifact(entry.name, child.name);
+      if (artifact) artifacts.push(artifact);
+    }
+  }
+
+  return artifacts;
+}
+
+function classifyPhaseArtifact(dir, name) {
+  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';
+
+  return {
+    dir,
+    name,
+    displayPath: dir ? `${dir}/${name}` : name,
+    phaseToken,
+    kind,
+  };
 }
 
 function padPhase(n) {
@@ -97,23 +151,23 @@ export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
   return updated;
 }
 
-export function cmdPhaseStatus(...args) {
-  const cwd = process.cwd();
-  const planningDir = join(cwd, '.planning');
-  const roadmapPath = join(planningDir, 'ROADMAP.md');
-  const [phaseNumber, status] = args;
-
-  if (!phaseNumber || !status) {
-    console.error('Usage: gsdd phase-status <phase-number> <not_started|todo|in_progress|done>');
-    process.exitCode = 1;
-    return;
-  }
-
-  if (!existsSync(roadmapPath)) {
-    console.error('No ROADMAP.md found. Run the new-project workflow first.');
-    process.exitCode = 1;
-    return;
-  }
+export function cmdPhaseStatus(...args) {
+  const cwd = process.cwd();
+  const planningDir = join(cwd, '.planning');
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const [phaseNumber, status] = args;
+
+  if (!phaseNumber || !status) {
+    console.error('Usage: gsdd phase-status <phase-number> <not_started|todo|in_progress|done>');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!existsSync(roadmapPath)) {
+    console.error('No ROADMAP.md found. Run the new-project workflow first.');
+    process.exitCode = 1;
+    return;
+  }
 
   try {
     const roadmap = readFileSync(roadmapPath, 'utf-8');
@@ -121,13 +175,14 @@ export function cmdPhaseStatus(...args) {
     const changed = updated !== roadmap;
     if (changed) {
       writeFileSync(roadmapPath, updated);
+      try { writeFingerprint(planningDir); } catch { /* best-effort */ }
     }
     output({ phase: phaseNumber, status, roadmap: '.planning/ROADMAP.md', changed });
-  } catch (error) {
-    console.error(error.message);
-    process.exitCode = 1;
-  }
-}
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
 
 export function cmdFindPhase(...args) {
   const cwd = process.cwd();
@@ -163,9 +218,9 @@ export function cmdFindPhase(...args) {
     return;
   }
 
-  const allFiles = existsSync(phasesDir) ? readdirSync(phasesDir) : [];
-  const plans = allFiles.filter((f) => f.includes('PLAN'));
-  const summaries = allFiles.filter((f) => f.includes('SUMMARY'));
+  const allArtifacts = listPhaseArtifacts(phasesDir);
+  const plans = allArtifacts.filter((artifact) => artifact.kind === 'PLAN');
+  const summaries = allArtifacts.filter((artifact) => artifact.kind === 'SUMMARY');
 
   const roadmap = readFileSync(roadmapPath, 'utf-8');
   const phases = parsePhaseStatuses(roadmap);

package/bin/lib/provenance.mjs

@@ -9,6 +9,23 @@ function normalizeCount(value) {
   return Number.isFinite(numeric) ? numeric : 'unknown';
 }
 
+function normalizeCheckpointWorkflow(workflow) {
+  const normalized = String(workflow || 'generic').trim().toLowerCase();
+  return ['phase', 'quick', 'generic'].includes(normalized) ? normalized : 'generic';
+}
+
+export function classifyCheckpointRouting(workflow) {
+  const normalizedWorkflow = normalizeCheckpointWorkflow(workflow);
+  const progressBlocks = normalizedWorkflow === 'phase' || normalizedWorkflow === 'quick';
+
+  return {
+    workflow: normalizedWorkflow,
+    routingClass: progressBlocks ? 'blocking' : 'informational',
+    progressBlocks,
+    resumeOwnsCleanup: true,
+  };
+}
+
 export function parseGitStatusShort(statusText = '') {
   const lines = statusText
     .replace(/\r\n/g, '\n')
@@ -48,6 +65,7 @@ export function buildProvenanceSnapshot({
   planning = {},
   git = {},
 } = {}) {
+  const checkpointRouting = classifyCheckpointRouting(checkpoint.workflow);
   const status = parseGitStatusShort(git.statusShort || '');
   const commitsAheadOfMain = normalizeCount(git.commitsAheadOfMain);
   const commitsAheadOfRemote = normalizeCount(git.commitsAheadOfRemote);
@@ -113,10 +131,11 @@ export function buildProvenanceSnapshot({
 
   return {
     checkpoint: {
-      workflow: checkpoint.workflow || 'generic',
+      workflow: checkpointRouting.workflow,
       phase: checkpoint.phase ?? null,
       runtime: checkpoint.runtime || 'unknown',
       hasNarrative: Boolean(checkpoint.hasNarrative),
+      routing: checkpointRouting,
     },
     planning: {
       currentPhase: planning.currentPhase || null,

package/bin/lib/rendering.mjs

@@ -30,6 +30,13 @@ agent: ${workflow.agent}
 ${workflowContent}`;
 }
 
+function buildPortableSkillEntries(workflows) {
+  return workflows.map((workflow) => ({
+    relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
+    content: renderSkillContent(workflow),
+  }));
+}
+
 function renderOpenCodeCommandContent(workflow) {
   const workflowContent = getWorkflowContent(workflow.workflow);
   return `---
@@ -85,6 +92,7 @@ function upsertBoundedBlock(existing, blockContent) {
 }
 
 export {
+  buildPortableSkillEntries,
   getDelegateContent,
   getWorkflowContent,
   renderAgentsBoundedBlock,