gsdd-cli 0.2.0 → 0.16.1

package/bin/lib/phase.mjs

@@ -7,6 +7,24 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from
 import { join, basename } from 'path';
 import { output } from './cli-utils.mjs';
 
+const PHASE_STATUS_MARKERS = {
+  not_started: '[ ]',
+  todo: '[ ]',
+  in_progress: '[-]',
+  done: '[x]',
+};
+
+const PHASE_MARKER_RE = '(\\[[ x]\\]|\\[-\\]|⬜|ðŸ"„|✅|⬜|🔄|✅)';
+const PHASE_TOKEN_RE = '(\\d+(?:\\.\\d+)*[a-z]?)';
+const PHASE_LINE_RE = new RegExp(
+  `^[-*]\\s*${PHASE_MARKER_RE}\\s*\\*\\*Phase\\s+${PHASE_TOKEN_RE}:\\s*(.+?)\\*\\*`,
+  'i'
+);
+const ROADMAP_PHASE_STATUS_RE = new RegExp(
+  `^(\\s*[-*]\\s*)${PHASE_MARKER_RE}(\\s*\\*\\*Phase\\s+${PHASE_TOKEN_RE}:.*)$`,
+  'i'
+);
+
 function findFiles(dir, prefix) {
   if (!existsSync(dir)) return [];
   return readdirSync(dir).filter((f) => f.startsWith(prefix) || f.startsWith(prefix.replace(/^0+/, '')));
@@ -20,13 +38,7 @@ function parsePhaseStatuses(roadmap) {
   const phases = [];
   const lines = roadmap.split('\n');
   for (const line of lines) {
-    // Supports:
-    // - checkbox statuses: [ ] / [x]
-    // - legacy emoji markers in ROADMAP templates: not started / in progress / done
-    // - mojibake-encoded variants that exist in some files
-    const match = line.match(
-      /^[-*]\s*(\[[ x]\]|\[-\]|⬜|ðŸ"„|✅|⬜|🔄|✅)\s*\*\*Phase\s+(\d+):\s*(.+?)\*\*/i
-    );
+    const match = line.match(PHASE_LINE_RE);
     if (match) {
       const rawStatus = match[1].toLowerCase();
       let status = 'not_started';
@@ -34,7 +46,7 @@ function parsePhaseStatuses(roadmap) {
       else if (rawStatus === '[-]') status = 'in_progress';
       else if (rawStatus === 'ðÿ"„' || rawStatus === '🔄') status = 'in_progress';
       phases.push({
-        number: parseInt(match[2], 10),
+        number: match[2],
         name: match[3].replace(/\*\*/g, '').split('-')[0].trim(),
         status,
       });
@@ -43,6 +55,80 @@ function parsePhaseStatuses(roadmap) {
   return phases;
 }
 
+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] || ''}`;
+}
+
+export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
+  const marker = PHASE_STATUS_MARKERS[status];
+  if (!marker) {
+    throw new Error(`Unsupported phase status: ${status}`);
+  }
+
+  const normalizedTarget = normalizePhaseToken(phaseNumber);
+  let matchCount = 0;
+
+  const updated = roadmap
+    .split('\n')
+    .map((line) => {
+      const match = line.match(ROADMAP_PHASE_STATUS_RE);
+      if (!match) return line;
+      if (normalizePhaseToken(match[4]) !== normalizedTarget) return line;
+      matchCount += 1;
+      return `${match[1]}${marker}${match[3]}`;
+    })
+    .join('\n');
+
+  if (matchCount === 0) {
+    throw new Error(`Phase ${phaseNumber} was not found in ROADMAP.md`);
+  }
+
+  if (matchCount > 1) {
+    throw new Error(`Phase ${phaseNumber} matched multiple ROADMAP.md entries`);
+  }
+
+  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;
+  }
+
+  try {
+    const roadmap = readFileSync(roadmapPath, 'utf-8');
+    const updated = updateRoadmapPhaseStatus(roadmap, phaseNumber, status);
+    const changed = updated !== roadmap;
+    if (changed) {
+      writeFileSync(roadmapPath, updated);
+    }
+    output({ phase: phaseNumber, status, roadmap: '.planning/ROADMAP.md', changed });
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
 export function cmdFindPhase(...args) {
   const cwd = process.cwd();
   const planningDir = join(cwd, '.planning');
@@ -67,7 +153,7 @@ export function cmdFindPhase(...args) {
     const summaries = findFiles(phasesDir, `${padPhase(phaseNum)}-SUMMARY`);
 
     output({
-      phase: parseInt(phaseNum, 10),
+      phase: normalizePhaseToken(phaseNum),
       directory: phasesDir,
       plans,
       summaries,
@@ -99,18 +185,18 @@ export function cmdVerify(...args) {
   const phaseNum = args[0];
   if (!phaseNum) {
     console.error('Usage: gsdd verify <phase-number>');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   if (!existsSync(planningDir)) {
     console.error('No .planning/ directory found.');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const planFile = findFiles(join(planningDir, 'phases'), `${padPhase(phaseNum)}-PLAN`)[0];
   if (!planFile) {
     console.error(`No plan found for phase ${phaseNum}`);
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const planPath = join(planningDir, 'phases', planFile);
@@ -183,14 +269,14 @@ export function cmdScaffold(...args) {
 
   if (type !== 'phase') {
     console.error('Usage: gsdd scaffold phase <number> [name]');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const phaseNum = rest[0];
   const phaseName = rest.slice(1).join(' ');
   if (!phaseNum) {
     console.error('Usage: gsdd scaffold phase <number> [name]');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const phasesDir = join(planningDir, 'phases');

package/bin/lib/plan-constants.mjs

@@ -0,0 +1,30 @@
+export const PLAN_CHECK_DIMENSIONS = [
+  'requirement_coverage',
+  'task_completeness',
+  'dependency_correctness',
+  'key_link_completeness',
+  'scope_sanity',
+  'must_have_quality',
+  'context_compliance',
+  'goal_achievement',
+  'approach_alignment',
+];
+
+export const MAX_CHECKER_CYCLES = 3;
+
+export const CHECKER_STATUSES = ['passed', 'issues_found'];
+
+export const CHECKER_JSON_SCHEMA = {
+  status: 'passed | issues_found',
+  summary: 'string',
+  issues: [
+    {
+      dimension: 'string',
+      severity: 'blocker | warning',
+      description: 'string',
+      plan: 'string',
+      task: 'string',
+      fix_hint: 'string',
+    },
+  ],
+};

package/bin/lib/provenance.mjs

@@ -0,0 +1,146 @@
+function normalizePrState(prState) {
+  if (!prState) return 'none';
+  return String(prState).trim().toLowerCase();
+}
+
+function normalizeCount(value) {
+  if (value === 'unknown' || value === null || value === undefined) return 'unknown';
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 'unknown';
+}
+
+export function parseGitStatusShort(statusText = '') {
+  const lines = statusText
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+
+  const files = [];
+  for (const line of lines) {
+    const match = line.match(/^(.)(.)\s+(.+)$/);
+    if (!match) continue;
+
+    const indexStatus = match[1];
+    const worktreeStatus = match[2];
+    if (indexStatus === '!' && worktreeStatus === '!') continue;
+
+    const filePath = match[3].replace(/\\/g, '/');
+    files.push({
+      path: filePath,
+      staged: indexStatus !== ' ' && indexStatus !== '?' && indexStatus !== '!',
+      unstaged: worktreeStatus !== ' ' && worktreeStatus !== '?' && worktreeStatus !== '!',
+      untracked: indexStatus === '?' || worktreeStatus === '?',
+    });
+  }
+
+  return {
+    files,
+    stagedCount: files.filter((file) => file.staged).length,
+    unstagedCount: files.filter((file) => file.unstaged).length,
+    untrackedCount: files.filter((file) => file.untracked).length,
+    dirty: files.length > 0,
+  };
+}
+
+export function buildProvenanceSnapshot({
+  checkpoint = {},
+  planning = {},
+  git = {},
+} = {}) {
+  const status = parseGitStatusShort(git.statusShort || '');
+  const commitsAheadOfMain = normalizeCount(git.commitsAheadOfMain);
+  const commitsAheadOfRemote = normalizeCount(git.commitsAheadOfRemote);
+  const prState = normalizePrState(git.prState);
+
+  const warnings = [];
+
+  if (status.dirty) {
+    warnings.push({
+      id: 'dirty_worktree',
+      severity: 'warning',
+      summary: 'Local worktree contains staged, unstaged, or untracked changes.',
+    });
+  }
+
+  if (commitsAheadOfMain !== 'unknown' && commitsAheadOfMain > 0) {
+    warnings.push({
+      id: 'ahead_of_main',
+      severity: 'warning',
+      summary: `${commitsAheadOfMain} commit(s) are ahead of main on the current branch.`,
+    });
+  }
+
+  if (commitsAheadOfRemote !== 'unknown' && commitsAheadOfRemote > 0) {
+    warnings.push({
+      id: 'unpushed_commits',
+      severity: 'warning',
+      summary: `${commitsAheadOfRemote} commit(s) are ahead of the tracked remote branch.`,
+    });
+  }
+
+  if (prState === 'none') {
+    warnings.push({
+      id: 'missing_pr',
+      severity: 'warning',
+      summary: 'No pull request is associated with the current branch.',
+    });
+  }
+
+  if (git.staleBranch) {
+    warnings.push({
+      id: 'stale_branch',
+      severity: 'warning',
+      summary: 'The current branch is stale or spent relative to the intended integration surface.',
+    });
+  }
+
+  if (git.mixedScope) {
+    warnings.push({
+      id: 'mixed_scope',
+      severity: 'warning',
+      summary: 'The current worktree appears to mix multiple write scopes or phases.',
+    });
+  }
+
+  if (git.materialCheckpointMismatch) {
+    warnings.push({
+      id: 'checkpoint_mismatch',
+      severity: 'acknowledgement_required',
+      summary: 'Checkpoint narrative truth materially understates or conflicts with the live branch/worktree truth.',
+    });
+  }
+
+  return {
+    checkpoint: {
+      workflow: checkpoint.workflow || 'generic',
+      phase: checkpoint.phase ?? null,
+      runtime: checkpoint.runtime || 'unknown',
+      hasNarrative: Boolean(checkpoint.hasNarrative),
+    },
+    planning: {
+      currentPhase: planning.currentPhase || null,
+      nextPhase: planning.nextPhase || null,
+      completedPhaseCount: Number.isFinite(Number(planning.completedPhaseCount))
+        ? Number(planning.completedPhaseCount)
+        : 0,
+    },
+    git: {
+      branch: git.branch || 'unknown',
+      prState,
+      commitsAheadOfMain,
+      commitsAheadOfRemote,
+      stagedCount: status.stagedCount,
+      unstagedCount: status.unstagedCount,
+      untrackedCount: status.untrackedCount,
+      dirty: status.dirty,
+    },
+    integrationSurface: {
+      staleBranch: Boolean(git.staleBranch),
+      mixedScope: Boolean(git.mixedScope),
+      materialCheckpointMismatch: Boolean(git.materialCheckpointMismatch),
+    },
+    warnings,
+    requiresAcknowledgement: warnings.some((warning) => warning.severity === 'acknowledgement_required'),
+  };
+}

package/bin/lib/templates.mjs

@@ -12,6 +12,23 @@ export function installProjectTemplates({ planningDir, distilledDir, agentsDir }
     if (existsSync(globalTemplatesDir)) {
       cpSync(globalTemplatesDir, localTemplatesDir, { recursive: true });
       console.log('  - copied templates to .planning/templates/');
+      // Warn-only by design: init should not fail on missing templates because
+      // the user may still proceed and fix later. The hard gate lives in
+      // `gsdd health` (E6/E7/E8) which reports these as errors. This is the
+      // first layer of the 3-layer scaffold defense (warn at init, error at
+      // health, regression tests in manifest suite).
+      const expectedSubdirs = ['delegates', 'research', 'codebase'];
+      for (const subdir of expectedSubdirs) {
+        if (!existsSync(join(localTemplatesDir, subdir))) {
+          console.log(`  - WARN: missing expected template subdir: ${subdir}/`);
+        }
+      }
+      const expectedRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
+      for (const file of expectedRootFiles) {
+        if (!existsSync(join(localTemplatesDir, file))) {
+          console.log(`  - WARN: missing expected root template file: ${file}`);
+        }
+      }
     } else {
       console.log('  - WARN: missing distilled/templates/; cannot copy templates');
     }