@opengsd/gsd-core 1.2.0 → 1.3.0-rc.1

package/get-shit-done/bin/lib/gap-checker.cjs

@@ -99,7 +99,9 @@ function formatGapTable(rows) {
   }
   const header = '| Source | Item | Status |\n|--------|------|--------|';
   const body = rows.map(r => {
-    const tick = r.status === 'Covered' ? '\u2713 Covered' : '\u2717 Not covered';
+    const tick = r.status === 'Covered' ? '\u2713 Covered'
+      : r.status === 'Missing from REQUIREMENTS.md' ? '\u26a0 Missing from REQUIREMENTS.md'
+      : '\u2717 Not covered';
     return `| ${r.source} | ${r.item} | ${tick} |`;
   }).join('\n');
   return `## Post-Planning Gap Analysis\n\n${header}\n${body}\n`;
@@ -116,7 +118,30 @@ function readGate(cwd) {
   return true;
 }
 
-function runGapAnalysis(cwd, phaseDir) {
+/**
+ * Normalize a raw `--phase-req-ids` argument into the scoping signal used by
+ * runGapAnalysis (#447). Mirrors §13's null/TBD skip semantics.
+ *
+ *   undefined           → flag absent: compare the whole REQUIREMENTS.md (back-compat)
+ *   null | '' | TBD     → no requirements mapped to this phase: skip the comparison
+ *   "REQ-01,REQ-02"     → restrict the comparison to these IDs
+ *
+ * Tolerates JSON-array-ish input (`["REQ-01","REQ-02"]`) since callers may pass
+ * the roadmap value through verbatim.
+ */
+function normalizePhaseReqIds(rawVal) {
+  if (rawVal === undefined) return undefined;
+  if (rawVal === null) return null;
+  const v = String(rawVal).replace(/["'[\]()]/g, '').trim();
+  if (v === '' || /^(null|tbd|none)$/i.test(v)) return null;
+  // Tolerate comma-, space-, or newline-separated lists (callers may pass the
+  // roadmap value verbatim, whose serialization is not guaranteed).
+  const ids = v.split(/[\s,]+/).map(s => s.trim()).filter(Boolean);
+  return ids.length === 0 ? null : ids;
+}
+
+function runGapAnalysis(cwd, phaseDir, options = {}) {
+  const phaseReqIds = normalizePhaseReqIds(options.phaseReqIds);
   if (!readGate(cwd)) {
     return {
       enabled: false,
@@ -131,7 +156,21 @@ function runGapAnalysis(cwd, phaseDir) {
 
   const reqPath = planningPaths(cwd).requirements;
   const reqMd = fs.existsSync(reqPath) ? fs.readFileSync(reqPath, 'utf-8') : '';
-  const reqItems = parseRequirements(reqMd).map(r => ({ ...r, source: 'REQUIREMENTS.md' }));
+  let reqItems = parseRequirements(reqMd).map(r => ({ ...r, source: 'REQUIREMENTS.md' }));
+
+  // Scope the requirements comparison to the phase's mapped REQ-IDs (#447).
+  // A phase that maps no requirements (phase_req_ids null/TBD) must not report
+  // every unrelated project REQ-ID as a gap — mirror §13's skip behavior.
+  // CONTEXT.md decisions (below) are always in scope regardless.
+  let ghostReqIds = [];
+  if (phaseReqIds === null) {
+    reqItems = [];
+  } else if (Array.isArray(phaseReqIds)) {
+    const wanted = new Set(phaseReqIds);
+    const foundIds = new Set(reqItems.map(r => r.id));
+    reqItems = reqItems.filter(r => wanted.has(r.id));
+    ghostReqIds = phaseReqIds.filter(id => !foundIds.has(id));
+  }
 
   // Read the phase directory once; reuse the listing for both context detection
   // and plan-file enumeration (avoids redundant readdirSync calls).
@@ -168,9 +207,12 @@ function runGapAnalysis(cwd, phaseDir) {
     };
   }
 
-  const rows = sortRows(detectCoverage(items, planText));
-  const uncovered = rows.filter(r => r.status === 'Not covered').length;
-  const covered = rows.length - uncovered;
+  const rows = sortRows([
+    ...detectCoverage(items, planText),
+    ...ghostReqIds.map(id => ({ source: 'REQUIREMENTS.md', item: id, status: 'Missing from REQUIREMENTS.md' })),
+  ]);
+  const covered = rows.filter(r => r.status === 'Covered').length;
+  const uncovered = rows.length - covered;
 
   const summary = uncovered === 0
     ? `\u2713 All ${rows.length} items covered by plans`
@@ -191,7 +233,13 @@ function cmdGapAnalysis(cwd, args, raw) {
     error('Usage: gap-analysis --phase-dir <path-to-phase-directory>');
   }
   const phaseDir = args[idx + 1];
-  const result = runGapAnalysis(cwd, phaseDir);
+
+  // Optional --phase-req-ids scopes the requirements comparison (#447).
+  // Absent → compare the whole REQUIREMENTS.md (back-compat).
+  const reqIdx = args.indexOf('--phase-req-ids');
+  const phaseReqIds = reqIdx === -1 ? undefined : (args[reqIdx + 1] ?? '');
+
+  const result = runGapAnalysis(cwd, phaseDir, { phaseReqIds });
   output(result, raw, result.table || result.summary);
 }
 
@@ -200,6 +248,7 @@ module.exports = {
   detectCoverage,
   formatGapTable,
   sortRows,
+  normalizePhaseReqIds,
   runGapAnalysis,
   cmdGapAnalysis,
 };

package/get-shit-done/bin/lib/installer-migration-report.cjs

@@ -122,6 +122,7 @@ const BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
   'hooks/gsd-update-banner.js',
   'hooks/gsd-validate-commit.sh',
   'hooks/gsd-workflow-guard.js',
+  'hooks/gsd-worktree-path-guard.js',
 ]));
 
 // Classify a blocked prompt-user action into one of the safe-default

package/get-shit-done/bin/lib/milestone.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, output, error } = require('./core.cjs');
+const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, normalizePhaseName, phaseTokenMatches, output, error } = require('./core.cjs');
 const { platformWriteSync, platformEnsureDir } = require('./shell-command-projection.cjs');
 const { planningPaths } = require('./planning-workspace.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
@@ -114,6 +114,64 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     error(`no phases found for milestone ${version} in ROADMAP.md`);
   }
 
+  // Guard: prevent marking complete when ROADMAP still lists phases that have
+  // no directory on disk (disk_status: no_directory). This catches the case
+  // where the active milestone was erroneously marked complete before phases
+  // were even started. Only fires when STATE.md confirms the current milestone
+  // version matches what is being completed — no false positives on fresh
+  // projects where phases haven't been scaffolded yet.
+  // Pass --force to override this guard.
+  if (!options.force) {
+    try {
+      // Only guard when STATE.md's milestone field matches the version being completed.
+      let stateVersion = null;
+      try {
+        const stateRaw = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf-8') : null;
+        if (stateRaw) {
+          const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
+          if (milestoneMatch) stateVersion = milestoneMatch[1].trim();
+        }
+      } catch { /* skip */ }
+
+      if (stateVersion && stateVersion === version) {
+        const { extractCurrentMilestone } = require('./core.cjs');
+        const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+        const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
+        const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+        const noDirectoryPhases = [];
+        let pm;
+        const phaseDirEntries = (() => {
+          try {
+            return fs.readdirSync(phasesDir, { withFileTypes: true })
+              .filter(e => e.isDirectory()).map(e => e.name);
+          } catch { return []; }
+        })();
+        while ((pm = phasePattern.exec(scopedContent)) !== null) {
+          const phaseNum = pm[1];
+          const normalized = normalizePhaseName(phaseNum);
+          // A phase has disk_status: 'no_directory' when no phase directory
+          // with a matching token exists on disk. Use the same phaseTokenMatches
+          // helper that roadmap.analyze uses to avoid false positives on decimal
+          // (2.1) and letter-suffix (12A) phase IDs.
+          const hasDirectory = phaseDirEntries.some(d => phaseTokenMatches(d, normalized));
+          if (!hasDirectory) {
+            noDirectoryPhases.push(phaseNum);
+          }
+        }
+        if (noDirectoryPhases.length > 0) {
+          error(
+            `Cannot mark milestone complete: ROADMAP lists ${noDirectoryPhases.length} unstarted phase(s) ` +
+            `(e.g. Phase ${noDirectoryPhases[0]}). Re-run with --force to override.`
+          );
+        }
+      }
+    } catch (e) {
+      // If the error came from our guard, re-throw it; otherwise skip silently.
+      if (e.message && e.message.startsWith('Cannot mark milestone complete:')) throw e;
+      // Phase scan failed or STATE version mismatch — allow completion to proceed.
+    }
+  }
+
   // Gather stats from phases (scoped to current milestone only)
   let phaseCount = 0;
   let totalPlans = 0;

package/get-shit-done/bin/lib/model-catalog.cjs

@@ -90,6 +90,21 @@ const RUNTIMES_WITH_REASONING_EFFORT = new Set(
     .map(([runtime]) => runtime)
 );
 
+const PROVIDER_PRESETS = catalog.providerPresets || {};
+
+// KNOWN_PROVIDERS excludes 'generic' — it is a sentinel (all null entries) that
+// forces users to supply model IDs via model_profile_overrides. It is not a
+// real catalog-backed provider (#49).
+const KNOWN_PROVIDERS = new Set(
+  Object.entries(PROVIDER_PRESETS)
+    .filter(([, tiers]) =>
+      Object.values(tiers).some((budgets) =>
+        budgets && Object.values(budgets).some((entry) => entry && entry.model)
+      )
+    )
+    .map(([name]) => name)
+);
+
 function nextTier(currentTier) {
   const order = ['light', 'standard', 'heavy'];
   const idx = order.indexOf(String(currentTier));
@@ -203,6 +218,8 @@ module.exports = {
   RUNTIME_PROFILE_MAP,
   KNOWN_RUNTIMES,
   RUNTIMES_WITH_REASONING_EFFORT,
+  PROVIDER_PRESETS,
+  KNOWN_PROVIDERS,
   nextTier,
   formatAgentToModelMapAsTable,
   getAgentToModelMapForProfile,

package/get-shit-done/bin/lib/phase-lifecycle.cjs

@@ -55,7 +55,6 @@ function deriveProgressFromRoadmap(roadmapContent) {
     let totalPlansSum = 0;
     const planCellPattern = /\|\s*\d+[^|]*\|\s*(\d+)\/(\d+)\s*\|/gi;
     let pm;
-    // eslint-disable-next-line no-cond-assign
     while ((pm = planCellPattern.exec(roadmapContent)) !== null) {
       totalPlansSum += parseInt(pm[2], 10);
     }

package/get-shit-done/bin/lib/review-reviewer-selection.cjs

@@ -15,6 +15,7 @@ const KNOWN_REVIEWER_SLUGS = [
   'opencode',
   'qwen',
   'cursor',
+  'antigravity',
   'ollama',
   'lm_studio',
   'llama_cpp',

package/get-shit-done/bin/lib/roadmap-command-router.cjs

@@ -1,7 +1,91 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const { ROADMAP_SUBCOMMANDS } = require('./command-aliases.cjs');
 const { routeCjsCommandFamily } = require('./cjs-command-router-adapter.cjs');
+const roadmapUpgrade = require('./roadmap-upgrade.cjs');
+const { planningDir } = require('./planning-workspace.cjs');
+const { loadConfig } = require('./core.cjs');
+
+/**
+ * Check each phase entry in a milestone-prefixed ROADMAP.md for W021 violations.
+ *
+ * W021: a phase whose ID integer prefix does not match its enclosing milestone's
+ * major version number.
+ *
+ * Sentinel milestones (0 = pre-milestone, 999 = backlog) are exempt.
+ *
+ * @param {string} content - ROADMAP.md content
+ * @returns {Array<{code:'W021', message:string}>}
+ */
+function checkW021(content) {
+  const warnings = [];
+
+  // Sentinel milestone integers exempt from W021
+  const SENTINELS = new Set([0, 999]);
+  const MIGRATION_CMD = 'gsd-tools roadmap upgrade --convention milestone-prefixed';
+
+  // Milestone section heading: ## [GSD] v2.0 — Label  OR  ## v2.0: Label  OR  ## Roadmap v2.0
+  //   OR  ## ✅ v2.0  OR  ## 🚧 v2.0  (emoji-prefixed variants used by roadmap templates)
+  // Capture the major integer.
+  const MILESTONE_RE = /^#{1,3}\s+(?:\[[^\]]+\]\s+|Roadmap\s+|[✅🚧]\s*)?v(\d+)\.\d+(?:\s|:|\s*—)/iu;
+
+  // Migrated phase heading: ### Phase M-NN: Name  (M-NN or unpadded M-N form)
+  const PHASE_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+)-(\d+)(?:-\d+)*\s*:/i;
+  // Unprefixed legacy phase heading: ### Phase N: Name  (no hyphen sub-index)
+  const UNPREFIXED_PHASE_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Za-z]?(?:\.\d+)*)\s*:/i;
+
+  let currentMilestoneMajor = null;
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const milestoneMatch = line.match(MILESTONE_RE);
+    if (milestoneMatch) {
+      currentMilestoneMajor = parseInt(milestoneMatch[1], 10);
+      continue;
+    }
+
+    const phaseMatch = line.match(PHASE_RE);
+    if (phaseMatch) {
+      const phaseMajor = parseInt(phaseMatch[1], 10);
+      if (SENTINELS.has(phaseMajor)) continue; // exempt
+
+      if (currentMilestoneMajor !== null && phaseMajor !== currentMilestoneMajor) {
+        const phaseId = `${phaseMatch[1]}-${phaseMatch[2]}`;
+        warnings.push({
+          code: 'W021',
+          message:
+            `Phase ID prefix mismatch: phase "${phaseId}" is listed under v${currentMilestoneMajor}.x ` +
+            `but its prefix (${phaseMajor}) does not match. ` +
+            `Run \`${MIGRATION_CMD}\` to fix.`,
+        });
+      }
+      continue;
+    }
+
+    // When the convention is active, an unprefixed heading (### Phase 1:) is itself a W021
+    // violation — it is missing the required M-NN prefix entirely.
+    const unprefixedMatch = line.match(UNPREFIXED_PHASE_RE);
+    if (unprefixedMatch && currentMilestoneMajor !== null) {
+      const rawId = unprefixedMatch[1];
+      // Skip if it matched PHASE_RE already (it didn't reach here in that case)
+      // Also skip if it looks like a bare integer whose prefix matches the section
+      // — those pass; only non-matching or non-prefixed forms fire W021.
+      const numericMajor = parseInt(rawId, 10);
+      if (!SENTINELS.has(numericMajor)) {
+        warnings.push({
+          code: 'W021',
+          message:
+            `Phase ID "${rawId}" is not in M-NN form (milestone-prefixed convention is active). ` +
+            `Run \`${MIGRATION_CMD}\` to migrate.`,
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
 
 /**
  * Manifest-backed roadmap subcommand router.
@@ -19,6 +103,56 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
       analyze: () => roadmap.cmdRoadmapAnalyze(cwd, raw),
       'update-plan-progress': () => roadmap.cmdRoadmapUpdatePlanProgress(cwd, args[2], raw),
       'annotate-dependencies': () => roadmap.cmdRoadmapAnnotateDependencies(cwd, args[2], raw),
+      'validate': () => {
+        const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+        let roadmapContent = '';
+        try {
+          roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+        } catch {
+          // ROADMAP.md missing — return empty warnings
+        }
+
+        // W021 only fires when phase_id_convention is explicitly 'milestone-prefixed'.
+        // Authoritative source: .planning/config.json (set by the upgrade command).
+        // Fallback: ROADMAP.md frontmatter (for projects that set the field there directly).
+        let convention;
+        try {
+          const cfg = loadConfig(cwd);
+          convention = cfg.phase_id_convention;
+        } catch {
+          convention = undefined;
+        }
+        if (convention === undefined || convention === null) {
+          // Fallback: read from ROADMAP.md frontmatter
+          const fmMatch = roadmapContent.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+          if (fmMatch) {
+            const kvMatch = fmMatch[1].match(/^phase_id_convention:\s*(.*)$/m);
+            if (kvMatch) {
+              const val = kvMatch[1].trim();
+              if (val !== 'null' && val !== '') {
+                convention = val.replace(/^["']|["']$/g, '');
+              }
+            }
+          }
+        }
+        const warnings = (convention === 'milestone-prefixed')
+          ? checkW021(roadmapContent)
+          : [];
+
+        const result = { warnings };
+        if (raw) process.stdout.write(JSON.stringify(result));
+        else process.stdout.write(JSON.stringify(result, null, 2));
+      },
+      'upgrade': () => {
+        const dryRun = !args.includes('--apply');
+        const convention = args.find((a, i) => args[i-1] === '--convention') || 'milestone-prefixed';
+        if (convention !== 'milestone-prefixed') {
+          process.stderr.write('Only --convention milestone-prefixed is supported\n');
+          process.exit(1);
+        }
+        const plan = roadmapUpgrade.computeMigrationPlan(cwd);
+        roadmapUpgrade.applyMigration(cwd, plan, { dryRun });
+      },
     },
   });
 }