@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/core.cjs

@@ -0,0 +1,744 @@
+/**
+ * Core — Shared utilities, constants, and internal helpers
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getPlanningRoot, PROJECTS_DIR } = require('./paths.cjs');
+
+// ─── Path helpers ────────────────────────────────────────────────────────────
+
+/** Normalize a relative path to always use forward slashes (cross-platform). */
+function toPosixPath(p) {
+  return p.split(path.sep).join('/');
+}
+
+// ─── Model Profile Table ─────────────────────────────────────────────────────
+
+const MODEL_PROFILES = {
+  'dgs-planner':              { quality: 'opus', balanced: 'opus',   budget: 'sonnet' },
+  'dgs-roadmapper':           { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'dgs-executor':             { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'dgs-phase-researcher':     { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'dgs-project-researcher':   { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'dgs-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'dgs-debugger':             { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'dgs-codebase-mapper':      { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' },
+  'dgs-verifier':             { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'dgs-plan-checker':         { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'dgs-integration-checker':  { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+
+// ─── Output helpers ───────────────────────────────────────────────────────────
+
+function output(result, raw, rawValue) {
+  if (raw && rawValue !== undefined) {
+    process.stdout.write(String(rawValue));
+  } else {
+    const json = JSON.stringify(result, null, 2);
+    // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
+    // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
+    if (json.length > 50000) {
+      const tmpPath = path.join(require('os').tmpdir(), `dgs-${Date.now()}.json`);
+      fs.writeFileSync(tmpPath, json, 'utf-8');
+      process.stdout.write('@file:' + tmpPath);
+    } else {
+      process.stdout.write(json);
+    }
+  }
+  process.exit(0);
+}
+
+function error(message) {
+  process.stderr.write('Error: ' + message + '\n');
+  process.exit(1);
+}
+
+// ─── File & Config utilities ──────────────────────────────────────────────────
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function loadConfig(cwd) {
+  const root = getPlanningRoot(cwd);
+  const newConfigPath = path.join(root, 'dgs.config.json');
+  const legacyConfigPath = path.join(root, 'config.json');
+  const configPath = fs.existsSync(newConfigPath) ? newConfigPath : legacyConfigPath;
+  const defaults = {
+    model_profile: 'balanced',
+    commit_docs: true,
+    search_gitignored: false,
+    branching_strategy: 'none',
+    phase_branch_template: 'dgs/{project}/phase-{phase}-{slug}',
+    milestone_branch_template: 'dgs/{project}/{milestone}-{slug}',
+    base_branch: 'main',
+    research: true,
+    plan_checker: true,
+    verifier: true,
+    parallelization: true,
+    brave_search: false,
+  };
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+
+    // Migrate deprecated "depth" key to "granularity" with value mapping
+    if ('depth' in parsed && !('granularity' in parsed)) {
+      const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
+      parsed.granularity = depthToGranularity[parsed.depth] || parsed.depth;
+      delete parsed.depth;
+      try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch {}
+    }
+
+    const get = (key, nested) => {
+      if (parsed[key] !== undefined) return parsed[key];
+      if (nested && parsed[nested.section] && parsed[nested.section][nested.field] !== undefined) {
+        return parsed[nested.section][nested.field];
+      }
+      return undefined;
+    };
+
+    const parallelization = (() => {
+      const val = get('parallelization');
+      if (typeof val === 'boolean') return val;
+      if (typeof val === 'object' && val !== null && 'enabled' in val) return val.enabled;
+      return defaults.parallelization;
+    })();
+
+    return {
+      model_profile: get('model_profile') ?? defaults.model_profile,
+      commit_docs: get('commit_docs', { section: 'planning', field: 'commit_docs' }) ?? defaults.commit_docs,
+      search_gitignored: get('search_gitignored', { section: 'planning', field: 'search_gitignored' }) ?? defaults.search_gitignored,
+      branching_strategy: get('branching_strategy', { section: 'git', field: 'branching_strategy' }) ?? defaults.branching_strategy,
+      phase_branch_template: get('phase_branch_template', { section: 'git', field: 'phase_branch_template' }) ?? defaults.phase_branch_template,
+      milestone_branch_template: get('milestone_branch_template', { section: 'git', field: 'milestone_branch_template' }) ?? defaults.milestone_branch_template,
+      base_branch: get('base_branch', { section: 'git', field: 'base_branch' }) ?? defaults.base_branch,
+      research: get('research', { section: 'workflow', field: 'research' }) ?? defaults.research,
+      plan_checker: get('plan_checker', { section: 'workflow', field: 'plan_check' }) ?? defaults.plan_checker,
+      verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
+      parallelization,
+      brave_search: get('brave_search') ?? defaults.brave_search,
+      model_overrides: parsed.model_overrides || null,
+      // v2 fields — passed through directly from config
+      current_project: get('current_project') ?? null,
+      v2_hint_shown: get('v2_hint_shown') ?? false,
+    };
+  } catch {
+    return { ...defaults, current_project: null, v2_hint_shown: false };
+  }
+}
+
+// ─── Git utilities ────────────────────────────────────────────────────────────
+
+function isGitIgnored(cwd, targetPath) {
+  try {
+    // --no-index checks .gitignore rules regardless of whether the file is tracked.
+    // Without it, git check-ignore returns "not ignored" for tracked files even when
+    // .gitignore explicitly lists them — a common source of confusion when .planning/
+    // was committed before being added to .gitignore.
+    execSync('git check-ignore -q --no-index -- ' + targetPath.replace(/[^a-zA-Z0-9._\-/]/g, ''), {
+      cwd,
+      stdio: 'pipe',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function execGit(cwd, args) {
+  try {
+    const escaped = args.map(a => {
+      if (/^[a-zA-Z0-9._\-/=:@]+$/.test(a)) return a;
+      return "'" + a.replace(/'/g, "'\\''") + "'";
+    });
+    const stdout = execSync('git ' + escaped.join(' '), {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+    return { exitCode: 0, stdout: stdout.trim(), stderr: '' };
+  } catch (err) {
+    return {
+      exitCode: err.status ?? 1,
+      stdout: (err.stdout ?? '').toString().trim(),
+      stderr: (err.stderr ?? '').toString().trim(),
+    };
+  }
+}
+
+// ─── Phase utilities ──────────────────────────────────────────────────────────
+
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function normalizePhaseName(phase) {
+  const match = String(phase).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+  if (!match) return phase;
+  const padded = match[1].padStart(2, '0');
+  const letter = match[2] ? match[2].toUpperCase() : '';
+  const decimal = match[3] || '';
+  return padded + letter + decimal;
+}
+
+function comparePhaseNum(a, b) {
+  const pa = String(a).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+  const pb = String(b).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+  if (!pa || !pb) return String(a).localeCompare(String(b));
+  const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10);
+  if (intDiff !== 0) return intDiff;
+  // No letter sorts before letter: 12 < 12A < 12B
+  const la = (pa[2] || '').toUpperCase();
+  const lb = (pb[2] || '').toUpperCase();
+  if (la !== lb) {
+    if (!la) return -1;
+    if (!lb) return 1;
+    return la < lb ? -1 : 1;
+  }
+  // Segment-by-segment decimal comparison: 12A < 12A.1 < 12A.1.2 < 12A.2
+  const aDecParts = pa[3] ? pa[3].slice(1).split('.').map(p => parseInt(p, 10)) : [];
+  const bDecParts = pb[3] ? pb[3].slice(1).split('.').map(p => parseInt(p, 10)) : [];
+  const maxLen = Math.max(aDecParts.length, bDecParts.length);
+  if (aDecParts.length === 0 && bDecParts.length > 0) return -1;
+  if (bDecParts.length === 0 && aDecParts.length > 0) return 1;
+  for (let i = 0; i < maxLen; i++) {
+    const av = Number.isFinite(aDecParts[i]) ? aDecParts[i] : 0;
+    const bv = Number.isFinite(bDecParts[i]) ? bDecParts[i] : 0;
+    if (av !== bv) return av - bv;
+  }
+  return 0;
+}
+
+function searchPhaseInDir(baseDir, relBase, normalized) {
+  try {
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+    const match = dirs.find(d => d.startsWith(normalized));
+    if (!match) return null;
+
+    const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
+    const phaseNumber = dirMatch ? dirMatch[1] : normalized;
+    const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
+    const phaseDir = path.join(baseDir, match);
+    const phaseFiles = fs.readdirSync(phaseDir);
+
+    const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').sort();
+    const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').sort();
+    const hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md');
+    const hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
+    const hasVerification = phaseFiles.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md');
+
+    const completedPlanIds = new Set(
+      summaries.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', ''))
+    );
+    const incompletePlans = plans.filter(p => {
+      const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+      return !completedPlanIds.has(planId);
+    });
+
+    return {
+      found: true,
+      directory: toPosixPath(path.join(relBase, match)),
+      phase_number: phaseNumber,
+      phase_name: phaseName,
+      phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null,
+      plans,
+      summaries,
+      incomplete_plans: incompletePlans,
+      has_research: hasResearch,
+      has_context: hasContext,
+      has_verification: hasVerification,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function findPhaseInternal(cwd, phase) {
+  if (!phase) return null;
+
+  const normalized = normalizePhaseName(phase);
+
+  // Resolve phases directory: v2 uses .planning/<project>/phases/, v1 uses .planning/phases/
+  let projectRoot;
+  try {
+    projectRoot = getProjectRoot(cwd);
+  } catch {
+    projectRoot = '.planning';
+  }
+  const phasesRel = path.join(projectRoot, 'phases');
+  const phasesDir = path.join(cwd, phasesRel);
+
+  // Search current phases first
+  const current = searchPhaseInDir(phasesDir, phasesRel, normalized);
+  if (current) return current;
+
+  // Search archived milestone phases (newest first)
+  // Archives are product-level, always under the planning root milestones/
+  const planRoot = getPlanningRoot(cwd);
+  const milestonesDir = path.join(planRoot, 'milestones');
+  if (!fs.existsSync(milestonesDir)) return null;
+
+  try {
+    const milestoneEntries = fs.readdirSync(milestonesDir, { withFileTypes: true });
+    const archiveDirs = milestoneEntries
+      .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+      .map(e => e.name)
+      .sort()
+      .reverse();
+
+    const planRootRel = path.relative(cwd, planRoot);
+    for (const archiveName of archiveDirs) {
+      const version = archiveName.match(/^(v[\d.]+)-phases$/)[1];
+      const archivePath = path.join(milestonesDir, archiveName);
+      const relBase = path.join(planRootRel, 'milestones', archiveName);
+      const result = searchPhaseInDir(archivePath, relBase, normalized);
+      if (result) {
+        result.archived = version;
+        return result;
+      }
+    }
+  } catch {}
+
+  return null;
+}
+
+function getArchivedPhaseDirs(cwd) {
+  const planRoot = getPlanningRoot(cwd);
+  const milestonesDir = path.join(planRoot, 'milestones');
+  const results = [];
+
+  if (!fs.existsSync(milestonesDir)) return results;
+
+  try {
+    const milestoneEntries = fs.readdirSync(milestonesDir, { withFileTypes: true });
+    // Find v*-phases directories, sort newest first
+    const phaseDirs = milestoneEntries
+      .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+      .map(e => e.name)
+      .sort()
+      .reverse();
+
+    const planRootRel = path.relative(cwd, planRoot);
+    for (const archiveName of phaseDirs) {
+      const version = archiveName.match(/^(v[\d.]+)-phases$/)[1];
+      const archivePath = path.join(milestonesDir, archiveName);
+      const entries = fs.readdirSync(archivePath, { withFileTypes: true });
+      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+
+      for (const dir of dirs) {
+        results.push({
+          name: dir,
+          milestone: version,
+          basePath: path.join(planRootRel, 'milestones', archiveName),
+          fullPath: path.join(archivePath, dir),
+        });
+      }
+    }
+  } catch {}
+
+  return results;
+}
+
+// ─── Roadmap & model utilities ────────────────────────────────────────────────
+
+function getRoadmapPhaseInternal(cwd, phaseNum) {
+  if (!phaseNum) return null;
+  // v2: look in project root (.planning/<project>/), v1: .planning/
+  let projectRoot;
+  try {
+    projectRoot = getProjectRoot(cwd);
+  } catch {
+    projectRoot = path.relative(cwd, getPlanningRoot(cwd)) || '.planning';
+  }
+  const roadmapPath = path.join(cwd, projectRoot, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) return null;
+
+  try {
+    const content = fs.readFileSync(roadmapPath, 'utf-8');
+    const escapedPhase = escapeRegex(phaseNum.toString());
+    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
+    const headerMatch = content.match(phasePattern);
+
+    // Fallback: match bold list-item format (- [ ] **Phase N: Name** - description)
+    const listPattern = new RegExp(`\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`, 'i');
+    const listMatch = !headerMatch ? content.match(listPattern) : null;
+
+    if (!headerMatch && !listMatch) return null;
+
+    let phaseName, section;
+    if (headerMatch) {
+      phaseName = headerMatch[1].trim();
+      const headerIndex = headerMatch.index;
+      const restOfContent = content.slice(headerIndex);
+      const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i);
+      const sectionEnd = nextHeaderMatch ? headerIndex + nextHeaderMatch.index : content.length;
+      section = content.slice(headerIndex, sectionEnd).trim();
+    } else {
+      phaseName = listMatch[1].trim();
+      const listIndex = listMatch.index;
+      const restOfContent = content.slice(listIndex);
+      const nextListMatch = restOfContent.match(/\n-\s+\[.\]\s+\*\*Phase\s+\d/i);
+      const sectionEnd = nextListMatch ? listIndex + nextListMatch.index : content.length;
+      section = content.slice(listIndex, sectionEnd).trim();
+    }
+
+    const goalMatch = section.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+    const goal = goalMatch ? goalMatch[1].trim() : null;
+
+    return {
+      found: true,
+      phase_number: phaseNum.toString(),
+      phase_name: phaseName,
+      goal,
+      section,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveModelInternal(cwd, agentType) {
+  const config = loadConfig(cwd);
+
+  // Check per-agent override first
+  const override = config.model_overrides?.[agentType];
+  if (override) {
+    return override === 'opus' ? 'inherit' : override;
+  }
+
+  // Fall back to profile lookup
+  const profile = config.model_profile || 'balanced';
+  const agentModels = MODEL_PROFILES[agentType];
+  if (!agentModels) return 'sonnet';
+  const resolved = agentModels[profile] || agentModels['balanced'] || 'sonnet';
+  return resolved === 'opus' ? 'inherit' : resolved;
+}
+
+// ─── Misc utilities ───────────────────────────────────────────────────────────
+
+function pathExistsInternal(cwd, targetPath) {
+  const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
+  try {
+    fs.statSync(fullPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function generateSlugInternal(text) {
+  if (!text) return null;
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function getMilestoneInfo(cwd) {
+  try {
+    const roadmap = fs.readFileSync(path.join(getPlanningRoot(cwd), 'ROADMAP.md'), 'utf-8');
+
+    // First: check for list-format roadmaps using 🚧 (in-progress) marker
+    // e.g. "- 🚧 **v2.1 Belgium** — Phases 24-28 (in progress)"
+    const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+\.\d+)\s+([^*]+)\*\*/);
+    if (inProgressMatch) {
+      return {
+        version: 'v' + inProgressMatch[1],
+        name: inProgressMatch[2].trim(),
+      };
+    }
+
+    // Second: heading-format roadmaps — strip shipped milestones in <details> blocks
+    const cleaned = roadmap.replace(/<details>[\s\S]*?<\/details>/gi, '');
+    // Extract version and name from the same ## heading for consistency
+    const headingMatch = cleaned.match(/## .*v(\d+\.\d+)[:\s]+([^\n(]+)/);
+    if (headingMatch) {
+      return {
+        version: 'v' + headingMatch[1],
+        name: headingMatch[2].trim(),
+      };
+    }
+    // Fallback: try bare version match
+    const versionMatch = cleaned.match(/v(\d+\.\d+)/);
+    return {
+      version: versionMatch ? versionMatch[0] : 'v1.0',
+      name: 'milestone',
+    };
+  } catch {
+    return { version: 'v1.0', name: 'milestone' };
+  }
+}
+
+/**
+ * Returns a filter function that checks whether a phase directory belongs
+ * to the current milestone based on ROADMAP.md phase headings.
+ * If no ROADMAP exists or no phases are listed, returns a pass-all filter.
+ */
+function getMilestonePhaseFilter(cwd) {
+  const milestonePhaseNums = new Set();
+  try {
+    const roadmap = fs.readFileSync(path.join(getPlanningRoot(cwd), 'ROADMAP.md'), 'utf-8');
+    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+    let m;
+    while ((m = phasePattern.exec(roadmap)) !== null) {
+      milestonePhaseNums.add(m[1]);
+    }
+  } catch {}
+
+  if (milestonePhaseNums.size === 0) {
+    const passAll = () => true;
+    passAll.phaseCount = 0;
+    return passAll;
+  }
+
+  const normalized = new Set(
+    [...milestonePhaseNums].map(n => (n.replace(/^0+/, '') || '0').toLowerCase())
+  );
+
+  function isDirInMilestone(dirName) {
+    const m = dirName.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
+    if (!m) return false;
+    return normalized.has(m[1].toLowerCase());
+  }
+  isDirInMilestone.phaseCount = milestonePhaseNums.size;
+  return isDirInMilestone;
+}
+
+// ─── v2 Path Resolution ──────────────────────────────────────────────────────
+
+/**
+ * System directories that live under .planning/ but are NOT project folders.
+ * Kept as a safety net — getProjectFolders() now scans .planning/projects/ directly
+ * and no longer relies on this set for filtering. The 'projects' entry prevents
+ * the projects container directory itself from being mistaken for a project.
+ */
+const SYSTEM_DIRS = new Set([
+  'phases', 'codebase', 'archive', 'todos', 'quick',
+  'debug', 'milestones', 'research', PROJECTS_DIR,
+]);
+
+/**
+ * Detect if this is a v2 (multi-project) installation.
+ * Requires both file existence AND valid DGS-generated content.
+ * PROJECTS.md must start with "# Projects", REPOS.md with "# Repos".
+ *
+ * @param {string} cwd - Working directory
+ * @returns {boolean}
+ */
+function isV2Install(cwd) {
+  const checks = [
+    { file: 'PROJECTS.md', header: '# Projects' },
+    { file: 'REPOS.md', header: '# Repos' },
+  ];
+  const planRoot = getPlanningRoot(cwd);
+  for (const { file, header } of checks) {
+    const filePath = path.join(planRoot, file);
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      if (content.startsWith(header)) return true;
+    } catch {
+      // File doesn't exist or unreadable — not a marker
+    }
+  }
+  return false;
+}
+
+/**
+ * Construct the absolute path to a project directory.
+ *
+ * Single centralised helper — all project path construction should flow
+ * through this function to keep the 'projects' path segment in one place.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} slug - Project slug
+ * @returns {string} Absolute path to the project directory
+ */
+function getProjectDir(cwd, slug) {
+  return path.join(getPlanningRoot(cwd), PROJECTS_DIR, slug);
+}
+
+/**
+ * Get the project root directory (relative path).
+ * - v2 with current_project set: returns .planning/projects/<project>
+ * - v2 without current_project: throws Error('NO_CURRENT_PROJECT_V2')
+ * - v1 (no v2 markers): returns '.planning'
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Relative path to project root
+ * @throws {Error} NO_CURRENT_PROJECT_V2 | PROJECT_NOT_FOUND | INVALID_PROJECT_NAME
+ */
+function getProjectRoot(cwd) {
+  const config = loadConfig(cwd);
+  const currentProject = (config.current_project || '').trim();
+
+  // Determine layout: root layout when planning root equals cwd
+  const planRoot = getPlanningRoot(cwd);
+  const isRootLayout = (planRoot === path.resolve(cwd));
+  const planRootRel = isRootLayout ? '.' : '.planning';
+
+  if (currentProject) {
+    // Validate project name — must be a simple slug, no path traversal
+    if (currentProject.includes('..') || currentProject.includes('/') || currentProject.includes('\\')) {
+      throw new Error('INVALID_PROJECT_NAME: ' + currentProject);
+    }
+
+    const projectDir = path.join(planRootRel, PROJECTS_DIR, currentProject);
+
+    // Validate directory exists on disk
+    if (!fs.existsSync(path.join(cwd, projectDir))) {
+      throw new Error('PROJECT_NOT_FOUND: ' + currentProject);
+    }
+
+    // Validate project is not completed
+    if (isProjectCompleted(cwd, currentProject)) {
+      throw new Error('PROJECT_COMPLETED: ' + currentProject);
+    }
+
+    return projectDir;
+  }
+
+  // No current_project — check if this is a v2 install
+  if (isV2Install(cwd)) {
+    throw new Error('NO_CURRENT_PROJECT_V2');
+  }
+
+  // v1 fallback — no v2 markers, return planning root relative path
+  return planRootRel;
+}
+
+/**
+ * Strict variant of getProjectRoot — signals that the caller MUST have a
+ * valid project root or the operation cannot proceed.
+ *
+ * Currently identical to getProjectRoot(), but exists as a distinct function
+ * for two reasons:
+ *   (a) Call sites that MUST have a project root use requireProjectRoot,
+ *       making the intent explicit in the code.
+ *   (b) If getProjectRoot ever gains a silent fallback mode,
+ *       requireProjectRoot remains strict.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Relative path to project root
+ * @throws {Error} NO_CURRENT_PROJECT_V2 | PROJECT_NOT_FOUND | INVALID_PROJECT_NAME
+ */
+function requireProjectRoot(cwd) {
+  return getProjectRoot(cwd);
+}
+
+/**
+ * Resolve a project-scoped relative path.
+ * e.g., resolveProjectPath(cwd, 'STATE.md') → '.planning/projects/auth-overhaul/STATE.md' (v2)
+ *        resolveProjectPath(cwd, 'STATE.md') → '.planning/STATE.md' (v1)
+ *        resolveProjectPath(cwd) → project root
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} [relativePath] - Path relative to project root
+ * @returns {string} Resolved relative path
+ */
+function resolveProjectPath(cwd, relativePath) {
+  const root = requireProjectRoot(cwd);
+  return relativePath ? path.join(root, relativePath) : root;
+}
+
+/**
+ * Check if a project is completed by reading its STATE.md directly.
+ *
+ * This is intentionally lightweight — reads STATUS line from STATE.md using
+ * safeReadFile (already in core.cjs) to avoid circular dependency on projects.cjs.
+ * Reads from .planning/projects/<slug>/STATE.md.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} slug - Project slug
+ * @returns {boolean} true if project STATUS is "completed" (case-insensitive)
+ */
+function isProjectCompleted(cwd, slug) {
+  const statePath = path.join(getProjectDir(cwd, slug), 'STATE.md');
+  const content = safeReadFile(statePath);
+  if (!content) return false;
+
+  const statusMatch = content.match(/Status:\s*(.+)/i);
+  if (!statusMatch) return false;
+
+  return statusMatch[1].trim().toLowerCase() === 'completed';
+}
+
+/**
+ * List project folders in a v2 install.
+ * Scans .planning/projects/ directly and returns directories that:
+ * - Don't start with '.'
+ * - Contain a STATE.md file (qualifying marker for project folders)
+ *
+ * Returns empty array if the projects/ directory does not exist, for v1 installs, or on any error.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string[]} Sorted array of project folder names
+ */
+function getProjectFolders(cwd) {
+  const projectsDir = path.join(getPlanningRoot(cwd), PROJECTS_DIR);
+
+  try {
+    return fs.readdirSync(projectsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .filter(e => !e.name.startsWith('.'))
+      .filter(e => {
+        // Must contain STATE.md to qualify as a project
+        return fs.existsSync(path.join(projectsDir, e.name, 'STATE.md'));
+      })
+      .map(e => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get the one-time v2 availability hint for v1 users.
+ * Returns hint text if v2_hint_shown is not set in config.
+ * Returns null if hint has already been shown.
+ * Note: Caller is responsible for persisting v2_hint_shown: true after displaying.
+ *
+ * @param {string} _cwd - Working directory (unused, reserved for future)
+ * @param {Object} config - Parsed config object
+ * @returns {string|null}
+ */
+function getV2Hint(_cwd, config) {
+  if (config.v2_hint_shown) return null;
+  return 'DGS v2 multi-project support available. Run /dgs:init-product to upgrade.';
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  output,
+  error,
+  safeReadFile,
+  loadConfig,
+  isGitIgnored,
+  execGit,
+  escapeRegex,
+  normalizePhaseName,
+  comparePhaseNum,
+  searchPhaseInDir,
+  findPhaseInternal,
+  getArchivedPhaseDirs,
+  getRoadmapPhaseInternal,
+  resolveModelInternal,
+  pathExistsInternal,
+  generateSlugInternal,
+  getMilestoneInfo,
+  getMilestonePhaseFilter,
+  toPosixPath,
+  resolveProjectPath,
+  getProjectRoot,
+  requireProjectRoot,
+  isV2Install,
+  getProjectFolders,
+  getV2Hint,
+  isProjectCompleted,
+  getProjectDir,
+};