gsdd-cli 0.3.1 → 0.18.0

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;
+  }
+}

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/models.mjs

@@ -15,6 +15,21 @@ export const DEFAULT_GIT_PROTOCOL = {
   pr: 'Follow the existing repo or team review workflow. Do not assume PR creation, timing, or naming unless explicitly requested.',
 };
 
+export const RIGOR_PROFILES = {
+  quick:    { researchDepth: 'fast',     workflow: { research: false, discuss: false, planCheck: false, verifier: true } },
+  balanced: { researchDepth: 'balanced', workflow: { research: true,  discuss: false, planCheck: true,  verifier: true } },
+  thorough: { researchDepth: 'deep',     workflow: { research: true,  discuss: true,  planCheck: true,  verifier: true } },
+};
+
+export const COST_PROFILES = {
+  budget:   { modelProfile: 'budget',   parallelization: false },
+  balanced: { modelProfile: 'balanced', parallelization: true  },
+  quality:  { modelProfile: 'quality',  parallelization: true  },
+};
+
+export function resolveRigor(id) { return RIGOR_PROFILES[id] ?? RIGOR_PROFILES.balanced; }
+export function resolveCost(id)  { return COST_PROFILES[id]  ?? COST_PROFILES.balanced;  }
+
 export const VALID_MODEL_PROFILES = ['quality', 'balanced', 'budget'];
 export const PORTABLE_AGENT_IDS = ['plan-checker', 'approach-explorer'];
 export const MODEL_RUNTIME_IDS = ['claude', 'opencode', 'codex'];
@@ -25,12 +40,12 @@ export function normalizeModelProfile(value) {
 }
 
 export function buildDefaultConfig({ autoAdvance = false } = {}) {
+  const rigor = resolveRigor('balanced');
+  const cost = resolveCost('balanced');
   const config = {
-    researchDepth: 'balanced',
-    parallelization: true,
+    ...rigor,
+    ...cost,
     commitDocs: true,
-    modelProfile: 'balanced',
-    workflow: { research: true, discuss: false, planCheck: true, verifier: true },
     gitProtocol: { ...DEFAULT_GIT_PROTOCOL },
     initVersion: 'v1.1',
   };