@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,1432 @@
+/**
+ * Repos — REPOS.md parse/write, repo discovery, prefix-match resolution,
+ *          .gitignore sync, path validation, PROJECTS.md scaffold
+ *
+ * This module is the foundation for all Phase 2 commands: init-product,
+ * add-repo, remove-repo, and the repos CLI subcommand.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, execGit, isV2Install, output, error } = require('./core.cjs');
+const { writeConfigField } = require('./config.cjs');
+const { getPlanningRoot, resetPaths } = require('./paths.cjs');
+// Lazy-loaded to avoid circular dependency (migration.cjs requires writeReposMd from this file)
+let _migration;
+function migration() {
+  if (!_migration) _migration = require('./migration.cjs');
+  return _migration;
+}
+
+// ─── REPOS.md Parse / Write ──────────────────────────────────────────────────
+
+/**
+ * Parse .planning/REPOS.md into structured data.
+ *
+ * Returns null if the file doesn't exist or doesn't start with '# Repos'.
+ * Returns { repos: [] } if the header exists but the table has no data rows.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {{ repos: Array<{name: string, path: string, url: string, description: string}> } | null}
+ */
+function parseReposMd(cwd) {
+  const filePath = path.join(getPlanningRoot(cwd), 'REPOS.md');
+  const content = safeReadFile(filePath);
+  if (!content) return null;
+
+  // v2 marker check — must start with '# Repos'
+  if (!content.startsWith('# Repos')) return null;
+
+  const lines = content.split('\n');
+  const repos = [];
+
+  // Find table header row (line starting with | containing Name)
+  let tableStart = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith('|') && lines[i].includes('Name')) {
+      tableStart = i;
+      break;
+    }
+  }
+
+  if (tableStart === -1) return { repos };
+
+  // Skip header row and separator row
+  let dataStart = tableStart + 2;
+
+  // Parse data rows
+  for (let i = dataStart; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line.startsWith('|')) break;
+
+    const cells = line.split('|').map(c => c.trim());
+    // Split on | gives empty first/last elements: |a|b|c| => ['', 'a', 'b', 'c', '']
+    // Need at least name and path (indices 1 and 2)
+    if (cells.length < 3) continue;
+
+    repos.push({
+      name: cells[1] || '',
+      path: cells[2] || '',
+      url: cells[3] || '',
+      description: cells[4] || '',
+    });
+  }
+
+  return { repos };
+}
+
+/**
+ * Write repos array to .planning/REPOS.md with standard format.
+ *
+ * Creates the '# Repos' header (v2 marker), explanatory text, and
+ * a properly formatted markdown table.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {Array<{name: string, path: string, url: string, description: string}>} repos
+ */
+function writeReposMd(cwd, repos) {
+  let content = '# Repos\n\n';
+  content += 'Registered repositories for this product. Managed by DGS — manual edits may be overwritten.\n\n';
+  content += '| Name | Path | GitHub URL | Description |\n';
+  content += '|------|------|------------|-------------|\n';
+
+  for (const repo of repos) {
+    content += `| ${repo.name} | ${repo.path} | ${repo.url || ''} | ${repo.description || ''} |\n`;
+  }
+
+  fs.writeFileSync(path.join(getPlanningRoot(cwd), 'REPOS.md'), content);
+}
+
+// ─── Eager Validation ─────────────────────────────────────────────────────────
+
+/**
+ * Validate REPOS.md entries eagerly: path format, disk existence, .git, duplicates.
+ *
+ * Separate from parseReposMd (which remains a pure parser) so callers can choose:
+ * parse-only for reading/writing, or validate for execution.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {{ repos: Array, errors: string[] }}
+ */
+function validateReposMdEager(cwd) {
+  const parsed = parseReposMd(cwd);
+  if (!parsed) {
+    return { repos: [], errors: ['No REPOS.md found.'] };
+  }
+
+  const errors = [];
+  const validatedRepos = [];
+  const seenAbsPaths = new Map(); // absPath -> repoName for duplicate detection
+
+  for (const repo of parsed.repos) {
+    // Validate path format: must start with ../ and not be deeper
+    if (!repo.path.startsWith('../')) {
+      errors.push(`Repo paths must use ../name format. Found: '${repo.path}' for repo '${repo.name}'.`);
+      continue;
+    }
+    if (repo.path.startsWith('../../') || repo.path.replace(/^\.\.\//, '').includes('../')) {
+      errors.push(`Repo paths must use ../name format. Found: '${repo.path}' for repo '${repo.name}'.`);
+      continue;
+    }
+
+    // Resolve to absolute path
+    const absPath = path.resolve(cwd, repo.path);
+
+    // Check directory exists
+    if (!fs.existsSync(absPath)) {
+      errors.push(`Repo '${repo.name}' not found at ${repo.path} -- check the path in REPOS.md or clone the repo there.`);
+      continue;
+    }
+
+    // Check .git exists
+    if (!fs.existsSync(path.join(absPath, '.git'))) {
+      errors.push(`Repo '${repo.name}' at ${repo.path} is not a git repository (no .git/).`);
+      continue;
+    }
+
+    // Check duplicate absolute paths
+    if (seenAbsPaths.has(absPath)) {
+      errors.push(`Duplicate path: repos '${seenAbsPaths.get(absPath)}' and '${repo.name}' both resolve to ${absPath}.`);
+      continue;
+    }
+
+    seenAbsPaths.set(absPath, repo.name);
+    validatedRepos.push(repo);
+  }
+
+  if (errors.length > 0) {
+    return { repos: [], errors };
+  }
+
+  return { repos: validatedRepos, errors: [] };
+}
+
+// ─── Longest-Prefix-Match Resolution ─────────────────────────────────────────
+
+/**
+ * Strip relative prefixes (./ and ../) from a path for matching purposes.
+ * Also collapses double separators and strips trailing slashes.
+ *
+ * @param {string} p - Path to normalize
+ * @returns {string} Normalized path without relative prefix
+ */
+function normalizeForMatch(p) {
+  return p.replace(/^\.\.\//, '').replace(/^\.\//, '').replace(/\/+/g, '/').replace(/\/$/, '');
+}
+
+/**
+ * Resolve a file path to its owning repo using longest-prefix-match.
+ *
+ * Critical edge case handling:
+ * - Trailing-slash normalization prevents 'web' from matching 'web-app/src/...'
+ * - Sorted longest-first so 'services/api/' matches before 'services/'
+ * - Handles both ./repo and ../repo path formats
+ * - Accepts absolute paths when cwd is provided
+ *
+ * @param {string} filePath - File path (relative or absolute)
+ * @param {Array<{name: string, path: string}>} repos - Array of repos
+ * @param {string} [cwd] - Working directory (product root) for absolute path resolution
+ * @returns {{name: string, path: string} | null} Matched repo or null
+ */
+function resolveFileToRepo(filePath, repos, cwd) {
+  if (!filePath) return null;
+  if (!repos || repos.length === 0) return null;
+
+  let inputPath = filePath;
+
+  // Handle absolute paths: resolve relative to cwd's parent (where sibling repos live)
+  if (cwd && path.isAbsolute(inputPath)) {
+    const parentDir = path.resolve(cwd, '..');
+    inputPath = path.relative(parentDir, inputPath);
+  }
+
+  // Normalize input: strip ../ and ./ prefixes, collapse double separators, strip trailing /
+  let normalized = normalizeForMatch(inputPath);
+
+  // Build match entries with trailing-slash normalization
+  const entries = repos.map(repo => {
+    const repoPath = normalizeForMatch(repo.path) + '/';
+    return { repo, matchPath: repoPath };
+  });
+
+  // Sort by matchPath length descending (longest first)
+  entries.sort((a, b) => b.matchPath.length - a.matchPath.length);
+
+  // Find first match — file path MUST have content after the repo prefix
+  // (i.e., normalized must start with matchPath which includes trailing /)
+  for (const { repo, matchPath } of entries) {
+    if (normalized.startsWith(matchPath)) {
+      return { name: repo.name, path: repo.path };
+    }
+  }
+
+  return null;
+}
+
+// ─── Repo Discovery ──────────────────────────────────────────────────────────
+
+/**
+ * Extract a description for a repo from package.json or README.
+ *
+ * Priority:
+ * 1. package.json 'description' field
+ * 2. First non-empty, non-header line from README.md/README/readme.md
+ * 3. Empty string
+ *
+ * @param {string} repoPath - Absolute path to repo directory
+ * @returns {string}
+ */
+function extractRepoDescription(repoPath) {
+  // Try package.json
+  try {
+    const pkgPath = path.join(repoPath, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    if (pkg.description) return pkg.description;
+  } catch {}
+
+  // Try README variants
+  const readmeNames = ['README.md', 'README', 'readme.md'];
+  for (const name of readmeNames) {
+    try {
+      const content = fs.readFileSync(path.join(repoPath, name), 'utf-8');
+      const lines = content.split('\n');
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        if (trimmed.startsWith('#')) continue;
+        // Return first non-empty, non-header line (max 100 chars)
+        return trimmed.length > 100 ? trimmed.slice(0, 100) : trimmed;
+      }
+    } catch {}
+  }
+
+  return '';
+}
+
+/**
+ * Discover git repos at depth-1 in the given directory.
+ *
+ * Scans for subdirectories containing .git/, excluding:
+ * - node_modules
+ * - .planning
+ * - Dot-directories (starting with '.')
+ * - Non-directories (files)
+ *
+ * Extracts GitHub URL from git remote and description from package.json/README.
+ *
+ * @param {string} cwd - Directory to scan
+ * @returns {Array<{name: string, path: string, url: string, description: string}>}
+ */
+function discoverRepos(cwd) {
+  const repos = [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return repos;
+  }
+
+  for (const entry of entries) {
+    // Skip non-directories
+    if (!entry.isDirectory()) continue;
+
+    const name = entry.name;
+
+    // Skip dot-directories
+    if (name.startsWith('.')) continue;
+
+    // Skip node_modules
+    if (name === 'node_modules') continue;
+
+    // Check for .git/
+    const gitDir = path.join(cwd, name, '.git');
+    if (!fs.existsSync(gitDir)) continue;
+
+    // Extract GitHub URL from git remote
+    let url = '';
+    try {
+      const result = execGit(cwd, ['-C', name, 'config', '--get', 'remote.origin.url']);
+      if (result.exitCode === 0 && result.stdout) {
+        url = result.stdout;
+      }
+    } catch {}
+
+    // Extract description
+    const description = extractRepoDescription(path.join(cwd, name));
+
+    repos.push({
+      name,
+      path: './' + name,
+      url,
+      description,
+    });
+  }
+
+  return repos;
+}
+
+/**
+ * Discover sibling git repos in the parent directory of the given directory.
+ *
+ * Scans the parent directory for subdirectories containing .git/, excluding:
+ * - The product root directory itself (selfName)
+ * - node_modules
+ * - Dot-directories (starting with '.')
+ * - Non-directories (files)
+ *
+ * Uses ../ path prefix for sibling repos (not ./ like local repos).
+ *
+ * @param {string} cwd - Directory to scan siblings of (product root)
+ * @returns {Array<{name: string, path: string, url: string, description: string}>}
+ */
+function discoverSiblingRepos(cwd) {
+  const repos = [];
+  const parentDir = path.resolve(cwd, '..');
+  const selfName = path.basename(path.resolve(cwd));
+
+  let entries;
+  try {
+    entries = fs.readdirSync(parentDir, { withFileTypes: true });
+  } catch {
+    return repos;
+  }
+
+  for (const entry of entries) {
+    // Skip non-directories
+    if (!entry.isDirectory()) continue;
+
+    const name = entry.name;
+
+    // Skip dot-directories
+    if (name.startsWith('.')) continue;
+
+    // Skip node_modules
+    if (name === 'node_modules') continue;
+
+    // Skip the product root directory itself
+    if (name === selfName) continue;
+
+    // Check for .git/
+    const gitDir = path.join(parentDir, name, '.git');
+    if (!fs.existsSync(gitDir)) continue;
+
+    // Extract GitHub URL from git remote
+    let url = '';
+    try {
+      const result = execGit(parentDir, ['-C', name, 'config', '--get', 'remote.origin.url']);
+      if (result.exitCode === 0 && result.stdout) {
+        url = result.stdout;
+      }
+    } catch {}
+
+    // Extract description
+    const description = extractRepoDescription(path.join(parentDir, name));
+
+    repos.push({
+      name,
+      path: '../' + name,
+      url,
+      description,
+    });
+  }
+
+  return repos;
+}
+
+// ─── .gitignore Sync ─────────────────────────────────────────────────────────
+
+const DGS_MARKER_START = '# DGS managed repos - do not edit below';
+const DGS_MARKER_END = '# end DGS managed repos';
+
+/**
+ * Sync .gitignore with DGS-managed repo paths.
+ *
+ * Manages a marked section in .gitignore between DGS marker comments.
+ * Preserves all user entries outside the marker section.
+ * On subsequent calls, replaces only the DGS section (no duplicates).
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {string[]} repoPaths - Array of repo paths (e.g., ['./web-app', './server'])
+ */
+function syncGitignore(cwd, repoPaths) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+
+  // Defensive: skip ../ paths (sibling repos are outside git tree)
+  repoPaths = repoPaths.filter(p => !p.startsWith('../'));
+  if (repoPaths.length === 0) return;
+
+  // Read existing content
+  let existing = '';
+  try {
+    existing = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch {}
+
+  // Normalize repo paths: strip ./ prefix, add trailing /
+  const normalizedPaths = repoPaths.map(p =>
+    p.replace(/^\.\//, '').replace(/\/$/, '') + '/'
+  );
+
+  // Build DGS section
+  const dgsSection = [
+    DGS_MARKER_START,
+    ...normalizedPaths,
+    DGS_MARKER_END,
+  ].join('\n');
+
+  // Find existing marker positions
+  const startIdx = existing.indexOf(DGS_MARKER_START);
+  const endIdx = existing.indexOf(DGS_MARKER_END);
+
+  let newContent;
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing DGS section
+    const prefix = existing.slice(0, startIdx).replace(/\n+$/, '');
+    const suffix = existing.slice(endIdx + DGS_MARKER_END.length).replace(/^\n+/, '');
+
+    const parts = [prefix, dgsSection, suffix].filter(p => p.length > 0);
+    newContent = parts.join('\n\n') + '\n';
+  } else {
+    // Add new DGS section
+    if (existing.trim()) {
+      newContent = existing.replace(/\n+$/, '') + '\n\n' + dgsSection + '\n';
+    } else {
+      newContent = dgsSection + '\n';
+    }
+  }
+
+  fs.writeFileSync(gitignorePath, newContent);
+}
+
+// ─── Path Validation ─────────────────────────────────────────────────────────
+
+/**
+ * Validate that registered repo paths exist on disk.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {Array<{name: string, path: string}>} repos - Array of repos to validate
+ * @returns {{ valid: Array, missing: Array }}
+ */
+function validateRepoPaths(cwd, repos) {
+  const valid = [];
+  const missing = [];
+
+  for (const repo of repos) {
+    const diskPath = path.resolve(cwd, repo.path);
+    if (fs.existsSync(diskPath)) {
+      valid.push(repo);
+    } else {
+      missing.push(repo);
+    }
+  }
+
+  return { valid, missing };
+}
+
+// ─── Path Conflict Detection ─────────────────────────────────────────────────
+
+/**
+ * Check if a new repo path conflicts with existing repo paths.
+ *
+ * A conflict exists when one path is a prefix of another at a directory
+ * boundary (trailing slash). This prevents ambiguous file-to-repo resolution.
+ *
+ * @param {string} newPath - New repo path to check (e.g., './services')
+ * @param {Array<{name: string, path: string}>} existingRepos - Current repos
+ * @returns {{ conflict: boolean, conflicting_repo?: Object }}
+ */
+function hasPathConflict(newPath, existingRepos) {
+  // Normalize: strip ./ and ../ prefixes, remove trailing /, add /
+  const newNorm = normalizeForMatch(newPath) + '/';
+
+  for (const repo of existingRepos) {
+    const existNorm = normalizeForMatch(repo.path) + '/';
+
+    if (newNorm.startsWith(existNorm) || existNorm.startsWith(newNorm)) {
+      return { conflict: true, conflicting_repo: repo };
+    }
+  }
+
+  return { conflict: false };
+}
+
+// ─── PROJECTS.md Scaffold ────────────────────────────────────────────────────
+
+/**
+ * Write .planning/PROJECTS.md with standard scaffold format.
+ *
+ * Creates the '# Projects' header (v2 marker), Active and Completed
+ * sections with table headers.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {Array} projects - Array of project objects (for future use)
+ */
+function writeProjectsMd(cwd, projects) {
+  let content = '# Projects\n\n';
+  content += '## Active\n\n';
+  content += '| Project | Status | Repos Touched | Current Phase |\n';
+  content += '|---------|--------|---------------|---------------|\n';
+
+  // Add active project rows
+  const active = (projects || []).filter(p => p.status !== 'completed');
+  for (const proj of active) {
+    content += `| ${proj.name || ''} | ${proj.status || ''} | ${proj.repos_touched || ''} | ${proj.current_phase || ''} |\n`;
+  }
+
+  content += '\n## Completed\n\n';
+  content += '| Project | Completed | Duration |\n';
+  content += '|---------|-----------|----------|\n';
+
+  // Add completed project rows
+  const completed = (projects || []).filter(p => p.status === 'completed');
+  for (const proj of completed) {
+    content += `| ${proj.name || ''} | ${proj.completed || ''} | ${proj.duration || ''} |\n`;
+  }
+
+  fs.writeFileSync(path.join(getPlanningRoot(cwd), 'PROJECTS.md'), content);
+}
+
+// ─── Plan Tag Auto-Population & Consistency Validation ──────────────────────
+
+/**
+ * Auto-populate <repos> tags in plan content from <files> path prefixes.
+ *
+ * For each <task> block containing a <files> tag, resolves file paths to
+ * owning repos via resolveFileToRepo (longest-prefix-match). Inserts or
+ * replaces <repos> tags with sorted, deduplicated repo names.
+ *
+ * @param {string} planContent - Raw PLAN.md content string
+ * @param {Array<{name: string, path: string}>} repos - Repos array (from parseReposMd)
+ * @returns {{ content: string, warnings: string[] }}
+ */
+function autoPopulateReposTags(planContent, repos) {
+  const warnings = [];
+
+  // Match each <task ...>...</task> block (non-greedy, dotall)
+  const taskPattern = /<task\b[^>]*>([\s\S]*?)<\/task>/g;
+
+  const updatedContent = planContent.replace(taskPattern, (fullMatch, taskBody) => {
+    // Extract <files> content if present
+    const filesMatch = taskBody.match(/<files>([\s\S]*?)<\/files>/);
+    if (!filesMatch) return fullMatch;
+
+    const filesContent = filesMatch[1];
+    const fileList = filesContent
+      .split(/[\n,]/)
+      .map(f => f.trim())
+      .filter(f => f);
+
+    // Resolve each file to its repo
+    const repoSet = new Set();
+    const unresolvedFiles = [];
+    for (const filePath of fileList) {
+      const resolved = resolveFileToRepo(filePath, repos);
+      if (resolved) {
+        repoSet.add(resolved.name);
+      } else {
+        unresolvedFiles.push(filePath);
+      }
+    }
+
+    // Handle repo-relative paths: if no repos could be derived from ANY files
+    // AND there are actual files to resolve, the files are likely repo-relative
+    if (repoSet.size === 0 && fileList.length > 0) {
+      // Files are repo-relative (can't derive repo from path alone)
+      // Preserve existing <repos> tag if present
+      if (/<repos>[\s\S]*?<\/repos>/.test(taskBody)) {
+        return fullMatch; // Leave unchanged
+      }
+      // No repos tag and no resolvable files — warn
+      warnings.push(`Cannot auto-populate <repos> for task — files appear repo-relative. Add <repos> tag manually.`);
+      return fullMatch;
+    }
+
+    // Warn about unresolved files when some files DID resolve (likely invalid paths)
+    for (const filePath of unresolvedFiles) {
+      warnings.push(`File '${filePath}' does not match any registered repo`);
+    }
+
+    // Build sorted repos tag content
+    const reposTagContent = Array.from(repoSet).sort().join(', ');
+    const newReposTag = `<repos>${reposTagContent}</repos>`;
+
+    // Check if <repos> tag already exists in this task
+    let updatedBody;
+    if (/<repos>[\s\S]*?<\/repos>/.test(taskBody)) {
+      // Replace existing <repos> tag
+      updatedBody = taskBody.replace(/<repos>[\s\S]*?<\/repos>/, newReposTag);
+    } else {
+      // Insert <repos> tag after </files>
+      updatedBody = taskBody.replace(/<\/files>/, `</files>\n  ${newReposTag}`);
+    }
+
+    return fullMatch.replace(taskBody, updatedBody);
+  });
+
+  return { content: updatedContent, warnings };
+}
+
+/**
+ * Validate consistency between <repos> and <files> tags in plan content.
+ *
+ * For each <task> block: extracts <repos> tag (listed repos) and <files> tag
+ * (derives repos via resolveFileToRepo). Compares to find extra (listed but
+ * not derived) and missing (derived but not listed) repos.
+ *
+ * @param {string} planContent - Raw PLAN.md content string
+ * @param {Array<{name: string, path: string}>} repos - Repos array (from parseReposMd)
+ * @returns {{ valid: boolean, mismatches: Array<{task: string, repos_listed: string[], repos_derived: string[], extra: string[], missing: string[]}> }}
+ */
+function validateReposConsistency(planContent, repos) {
+  const mismatches = [];
+  const taskPattern = /<task\b[^>]*>([\s\S]*?)<\/task>/g;
+  let match;
+
+  while ((match = taskPattern.exec(planContent)) !== null) {
+    const taskBody = match[1];
+
+    // Extract task name
+    const nameMatch = taskBody.match(/<name>([\s\S]*?)<\/name>/);
+    const taskName = nameMatch ? nameMatch[1].trim() : 'unnamed';
+
+    // Extract <files> content and derive repos
+    const filesMatch = taskBody.match(/<files>([\s\S]*?)<\/files>/);
+    const fileList = filesMatch
+      ? filesMatch[1].split(/[\n,]/).map(f => f.trim()).filter(f => f)
+      : [];
+
+    const derivedSet = new Set();
+    for (const filePath of fileList) {
+      const resolved = resolveFileToRepo(filePath, repos);
+      if (resolved) derivedSet.add(resolved.name);
+    }
+    const repos_derived = Array.from(derivedSet).sort();
+
+    // Extract <repos> content (listed repos)
+    const reposMatch = taskBody.match(/<repos>([\s\S]*?)<\/repos>/);
+    const repos_listed = reposMatch
+      ? reposMatch[1].split(',').map(r => r.trim()).filter(r => r).sort()
+      : [];
+
+    // If no repos could be derived from files (repo-relative paths),
+    // trust the explicit <repos> tag — no mismatch
+    if (repos_derived.length === 0 && repos_listed.length > 0) {
+      continue; // repo-relative files with explicit repos tag — valid
+    }
+
+    // Compare
+    const extra = repos_listed.filter(r => !repos_derived.includes(r));
+    const missing = repos_derived.filter(r => !repos_listed.includes(r));
+
+    if (extra.length > 0 || missing.length > 0) {
+      mismatches.push({ task: taskName, repos_listed, repos_derived, extra, missing });
+    }
+  }
+
+  return { valid: mismatches.length === 0, mismatches };
+}
+
+// ─── Layout Detection ─────────────────────────────────────────────────────────
+
+/**
+ * Detect the suggested layout mode for a repo based on its contents.
+ *
+ * Heuristic (checked in order):
+ * 1. .planning/ with config files -> dotplanning (existing setup)
+ * 2. dgs.config.json at root with planningRoot:'.' -> root (already root setup)
+ * 3. Repo is "empty-ish" (no source code indicators) AND no .planning/ -> root
+ * 4. Planning artifacts at root (PROJECT.md, ROADMAP.md) without .planning/ -> root
+ * 5. Default -> dotplanning (safer default)
+ *
+ * @param {string} cwd - Working directory (repo root)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdDetectLayout(cwd, raw) {
+  const signals = [];
+  // Pre-init detection: must check .planning/ directly (not via getPlanningRoot)
+  const DOT_PLANNING_DIR = '.planning';
+  const dotPlanning = path.join(cwd, DOT_PLANNING_DIR);
+
+  // Signal 1: .planning/ directory with config files
+  if (
+    fs.existsSync(path.join(dotPlanning, 'dgs.config.json')) ||
+    fs.existsSync(path.join(dotPlanning, 'config.json'))
+  ) {
+    signals.push('existing .planning/ directory with config files');
+    output({ suggested: 'dotplanning', signals }, raw);
+    return;
+  }
+
+  // Signal 2: dgs.config.json at root with planningRoot: '.'
+  const rootConfigPath = path.join(cwd, 'dgs.config.json');
+  if (fs.existsSync(rootConfigPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(rootConfigPath, 'utf-8'));
+      if (config.planningRoot === '.') {
+        signals.push('dgs.config.json at root with planningRoot: "."');
+        output({ suggested: 'root', signals }, raw);
+        return;
+      }
+    } catch { /* malformed config — continue detection */ }
+  }
+
+  // Signal 3: Empty-ish repo (no source code indicators at depth 1)
+  const hasDotPlanning = fs.existsSync(dotPlanning);
+  if (!hasDotPlanning) {
+    let hasSourceIndicators = false;
+    try {
+      const entries = fs.readdirSync(cwd, { withFileTypes: true });
+      const SOURCE_EXTENSIONS = ['.ts', '.js', '.py', '.go', '.rs', '.java'];
+
+      for (const entry of entries) {
+        const name = entry.name;
+        // Skip hidden files/dirs
+        if (name.startsWith('.')) continue;
+
+        // Check for source code directories
+        if (entry.isDirectory() && (name === 'src' || name === 'lib')) {
+          hasSourceIndicators = true;
+          break;
+        }
+
+        // Check for package.json
+        if (name === 'package.json') {
+          hasSourceIndicators = true;
+          break;
+        }
+
+        // Check for source code files at depth 1
+        if (entry.isFile()) {
+          const ext = path.extname(name);
+          if (SOURCE_EXTENSIONS.includes(ext)) {
+            hasSourceIndicators = true;
+            break;
+          }
+        }
+      }
+    } catch { /* can't read dir — treat as not empty-ish */ hasSourceIndicators = true; }
+
+    if (!hasSourceIndicators) {
+      signals.push('repo is empty-ish (no source code indicators at depth 1)');
+      output({ suggested: 'root', signals }, raw);
+      return;
+    }
+  }
+
+  // Signal 4: Planning artifacts at root without .planning/
+  if (!hasDotPlanning) {
+    const hasPlanningArtifacts =
+      fs.existsSync(path.join(cwd, 'PROJECT.md')) ||
+      fs.existsSync(path.join(cwd, 'ROADMAP.md'));
+    if (hasPlanningArtifacts) {
+      signals.push('planning artifacts (PROJECT.md or ROADMAP.md) at root without .planning/');
+      output({ suggested: 'root', signals }, raw);
+      return;
+    }
+  }
+
+  // Signal 5: .planning/ directory exists (even without config files)
+  if (hasDotPlanning) {
+    signals.push('existing .planning/ directory');
+  }
+
+  // Default: dotplanning (safer default)
+  signals.push('default (no root-mode signals detected)');
+  output({ suggested: 'dotplanning', signals }, raw);
+}
+
+// ─── Root-Layout .gitignore ───────────────────────────────────────────────────
+
+const DGS_ROOT_MARKER_START = '# DGS - Root Layout';
+const DGS_ROOT_MARKER_END = '# end DGS root layout';
+
+/**
+ * Generate or append a root-layout .gitignore with DGS section.
+ *
+ * Creates .gitignore if missing, appends DGS section if .gitignore already exists.
+ * Uses marker comments for idempotent section replacement on repeated calls.
+ *
+ * @param {string} cwd - Working directory (repo root)
+ */
+function generateRootGitignore(cwd) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+
+  // Build DGS root-layout section
+  const dgsSection = [
+    DGS_ROOT_MARKER_START,
+    '# This repo is a dedicated DGS planning repository.',
+    '# Planning artifacts are tracked; transient files are ignored.',
+    '',
+    '# Transient artifacts',
+    'node_modules/',
+    '*.log',
+    '*.tmp',
+    '.cache/',
+    '',
+    '# OS/Editor files',
+    '.DS_Store',
+    'Thumbs.db',
+    '.vscode/',
+    '.idea/',
+    '*.swp',
+    '*.swo',
+    '*~',
+    '',
+    '# DGS config (may contain API keys)',
+    'dgs.config.json',
+    '',
+    '# DGS review keys (contains API keys)',
+    'review-keys.json',
+    DGS_ROOT_MARKER_END,
+  ].join('\n');
+
+  // Read existing content
+  let existing = '';
+  try {
+    existing = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch { /* file doesn't exist yet */ }
+
+  // Find existing marker positions
+  const startIdx = existing.indexOf(DGS_ROOT_MARKER_START);
+  const endIdx = existing.indexOf(DGS_ROOT_MARKER_END);
+
+  let newContent;
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing DGS section
+    const prefix = existing.slice(0, startIdx).replace(/\n+$/, '');
+    const suffix = existing.slice(endIdx + DGS_ROOT_MARKER_END.length).replace(/^\n+/, '');
+    const parts = [prefix, dgsSection, suffix].filter(p => p.length > 0);
+    newContent = parts.join('\n\n') + '\n';
+  } else if (existing.trim()) {
+    // Append to existing content
+    newContent = existing.replace(/\n+$/, '') + '\n\n' + dgsSection + '\n';
+  } else {
+    // Create new file
+    newContent = dgsSection + '\n';
+  }
+
+  fs.writeFileSync(gitignorePath, newContent);
+}
+
+// ─── CLI Command Functions ───────────────────────────────────────────────────
+
+/**
+ * List all registered repos from REPOS.md.
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposList(cwd, raw) {
+  const result = parseReposMd(cwd);
+  if (!result) {
+    error('No REPOS.md found. Run /dgs:init-product first.');
+  }
+  output({ repos: result.repos }, raw);
+}
+
+/**
+ * Register a new repo in REPOS.md.
+ * Validates: path exists, has .git/, no name duplicate, no path conflict.
+ * Updates .gitignore after adding.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} repoPath - Path to repo (e.g., './new-repo')
+ * @param {Object} options - { name?: string, desc?: string }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposAdd(cwd, repoPath, options, raw) {
+  if (!repoPath) {
+    error('Usage: repos add <path> [--name N] [--desc D]');
+  }
+
+  // Enforce ../name format (breaking change: only sibling repos accepted)
+  if (!repoPath.startsWith('../')) {
+    error('Repo paths must use ../name format.');
+  }
+  // Reject deeper paths like ../../shared-libs/common
+  if (repoPath.startsWith('../../') || repoPath.replace(/^\.\.\//, '').includes('../')) {
+    error('Repo paths must use ../name format.');
+  }
+
+  const normalized = repoPath.replace(/\/+$/, '');
+
+  // Validate path exists on disk using path.resolve
+  const diskPath = path.resolve(cwd, normalized);
+  if (!fs.existsSync(diskPath)) {
+    const repoName = options.name || path.basename(normalized);
+    error(`Repo '${repoName}' not found at ${normalized} -- check the path in REPOS.md or clone the repo there.`);
+  }
+
+  // Validate .git/ exists
+  if (!fs.existsSync(path.join(diskPath, '.git'))) {
+    const repoName = options.name || path.basename(normalized);
+    error(`Repo '${repoName}' at ${normalized} is not a git repository (no .git/).`);
+  }
+
+  // Parse existing REPOS.md
+  const existing = parseReposMd(cwd);
+  if (!existing) {
+    error('No REPOS.md found. Run /dgs:init-product first.');
+  }
+
+  // Derive repo name
+  const repoName = options.name || path.basename(normalized);
+
+  // Check duplicate name
+  if (existing.repos.some(r => r.name === repoName)) {
+    error(`Repo '${repoName}' already exists in REPOS.md. Use --name to provide a different name.`);
+  }
+
+  // Check path conflict
+  const conflict = hasPathConflict(normalized, existing.repos);
+  if (conflict.conflict) {
+    error(`Path conflict: '${normalized}' conflicts with existing repo '${conflict.conflicting_repo.name}' at '${conflict.conflicting_repo.path}'. One path is a prefix of the other.`);
+  }
+
+  // Extract GitHub URL
+  let url = '';
+  try {
+    const gitResult = execGit(diskPath, ['config', '--get', 'remote.origin.url']);
+    if (gitResult.exitCode === 0 && gitResult.stdout) {
+      url = gitResult.stdout;
+    }
+  } catch {}
+
+  // Extract description
+  const description = options.desc || extractRepoDescription(diskPath);
+
+  // Build new repo entry
+  const newRepo = { name: repoName, path: normalized, url, description };
+
+  // Append and write
+  const repos = [...existing.repos, newRepo];
+  writeReposMd(cwd, repos);
+
+  // Sync .gitignore only for ./ paths (../repo paths are outside product root)
+  const localPaths = repos.map(r => r.path).filter(p => p.startsWith('./'));
+  if (localPaths.length > 0) {
+    syncGitignore(cwd, localPaths);
+  }
+
+  output({ added: true, repo: newRepo }, raw);
+}
+
+/**
+ * Unregister a repo from REPOS.md.
+ * Checks active project references unless --force is used.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} repoName - Name of repo to remove
+ * @param {Object} options - { force?: boolean }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposRemove(cwd, repoName, options, raw) {
+  if (!repoName) {
+    error('Usage: repos remove <name> [--force]');
+  }
+
+  const existing = parseReposMd(cwd);
+  if (!existing) {
+    error('No REPOS.md found. Run /dgs:init-product first.');
+  }
+
+  const repo = existing.repos.find(r => r.name === repoName);
+  if (!repo) {
+    error(`Repo '${repoName}' not found in REPOS.md.`);
+  }
+
+  // Check active project references (unless --force)
+  if (!options.force) {
+    const referencingProjects = scanRepoReferences(cwd, repoName);
+    if (referencingProjects.length > 0) {
+      output({
+        removed: false,
+        warning: 'Active projects reference this repo',
+        projects: referencingProjects,
+        repo: repoName,
+      }, raw);
+      return;
+    }
+  }
+
+  // Remove and write
+  const repos = existing.repos.filter(r => r.name !== repoName);
+  writeReposMd(cwd, repos);
+
+  // Sync .gitignore only for ./ paths (../repo paths are outside product root)
+  const localPaths = repos.map(r => r.path).filter(p => p.startsWith('./'));
+  if (localPaths.length > 0) {
+    syncGitignore(cwd, localPaths);
+  }
+
+  output({ removed: true, repo: repoName }, raw);
+}
+
+/**
+ * Scan plan files for references to a repo name in <repos> tags.
+ * Returns array of project/phase identifiers that reference the repo.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} repoName - Repo name to search for
+ * @returns {string[]} List of referencing locations
+ */
+function scanRepoReferences(cwd, repoName) {
+  const references = [];
+  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+
+  try {
+    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name);
+
+    for (const phaseDir of phaseDirs) {
+      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      const planFiles = fs.readdirSync(fullPhaseDir)
+        .filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+
+      for (const planFile of planFiles) {
+        const content = safeReadFile(path.join(fullPhaseDir, planFile));
+        if (!content) continue;
+
+        const reposMatches = content.match(/<repos>([^<]+)<\/repos>/g);
+        if (!reposMatches) continue;
+
+        for (const match of reposMatches) {
+          const inner = match.replace(/<\/?repos>/g, '');
+          const names = inner.split(',').map(n => n.trim());
+          if (names.includes(repoName)) {
+            references.push(`${phaseDir}/${planFile}`);
+            break;
+          }
+        }
+      }
+    }
+  } catch {}
+
+  return references;
+}
+
+/**
+ * Validate all registered repo paths exist on disk.
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposValidate(cwd, raw) {
+  const existing = parseReposMd(cwd);
+  if (!existing) {
+    error('No REPOS.md found. Run /dgs:init-product first.');
+  }
+
+  const result = validateRepoPaths(cwd, existing.repos);
+  output({
+    valid: result.valid,
+    missing: result.missing,
+    total: existing.repos.length,
+  }, raw);
+}
+
+/**
+ * Resolve a file path to its owning repo.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} filePath - File path to resolve
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposResolve(cwd, filePath, raw) {
+  if (!filePath) {
+    error('Usage: repos resolve <filepath>');
+  }
+
+  const existing = parseReposMd(cwd);
+  if (!existing) {
+    error('No REPOS.md found. Run /dgs:init-product first.');
+  }
+
+  const match = resolveFileToRepo(filePath, existing.repos);
+  if (match) {
+    output({ resolved: true, repo: match.name, path: match.path }, raw);
+  } else {
+    output({ resolved: false, repo: null, location: 'product' }, raw);
+  }
+}
+
+/**
+ * Initialize a product folder structure (v2 mode).
+ * Creates REPOS.md, PROJECTS.md, syncs .gitignore, updates config.
+ *
+ * Supports layout option:
+ * - layout='root': Config-first pattern — writes dgs.config.json at repo root
+ *   with planningRoot:'.', then creates all artifacts at repo root (no .planning/).
+ * - layout=null (default): Standard .planning/ layout (unchanged).
+ *
+ * @param {string} cwd - Working directory
+ * @param {Object} options - { productName?: string, layout?: string }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposInitProduct(cwd, options, raw) {
+  const isRootMode = options.layout === 'root';
+
+  // ── Root-mode: Config-first pattern ───────────────────────────────────────
+  if (isRootMode) {
+    // Write dgs.config.json FIRST so getPlanningRoot returns repo root
+    const rootConfigPath = path.join(cwd, 'dgs.config.json');
+    fs.writeFileSync(rootConfigPath, JSON.stringify({ planningRoot: '.' }, null, 2));
+    resetPaths(); // Clear stale cache so getPlanningRoot resolves to cwd
+
+    // Check if already initialized (idempotency)
+    if (isV2Install(cwd)) {
+      // Silently ensure v3.0 directories exist (backfill for upgrades)
+      const ideasStates = ['pending', 'rejected', 'done'];
+      for (const st of ideasStates) {
+        fs.mkdirSync(path.join(getPlanningRoot(cwd), 'ideas', st), { recursive: true });
+      }
+      fs.mkdirSync(path.join(getPlanningRoot(cwd), 'specs'), { recursive: true });
+      fs.mkdirSync(path.join(getPlanningRoot(cwd), 'docs', 'product'), { recursive: true });
+      error('Product already initialized. Use /dgs:progress to see status.');
+    }
+  } else {
+    // ── Standard layout: existing v1/v2 checks ────────────────────────────
+    // Check if user previously declined v1-to-v2 migration
+    const configPath = path.join(getPlanningRoot(cwd), 'config.json');
+    let existingConfig = {};
+    try {
+      existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch { /* no config yet */ }
+    if (existingConfig.v1_decline_migration) {
+      output({
+        v1_declined: true,
+        message: 'v1 mode preserved (migration was previously declined). Your v1 setup continues to work unchanged.',
+      }, raw);
+      return;
+    }
+
+    // Check for v1 install (existing .planning/PROJECT.md without v2 markers)
+    const v1Check = migration().detectV1Install(cwd);
+    if (v1Check.isV1) {
+      // Return v1 detection info — workflow handles the user prompt
+      output({
+        v1_detected: true,
+        project_name: v1Check.projectName,
+        slug: v1Check.slug,
+      }, raw);
+      return;
+    }
+
+    // Check if already v2
+    if (isV2Install(cwd)) {
+      // Silently ensure v3.0 directories exist (backfill for upgrades)
+      const ideasStates = ['pending', 'rejected', 'done'];
+      for (const st of ideasStates) {
+        fs.mkdirSync(path.join(getPlanningRoot(cwd), 'ideas', st), { recursive: true });
+      }
+      fs.mkdirSync(path.join(getPlanningRoot(cwd), 'specs'), { recursive: true });
+      fs.mkdirSync(path.join(getPlanningRoot(cwd), 'docs', 'product'), { recursive: true });
+      // Add .gitkeep files if directories are empty
+      const dirsToKeep = [
+        path.join(getPlanningRoot(cwd), 'ideas', 'pending', '.gitkeep'),
+        path.join(getPlanningRoot(cwd), 'ideas', 'rejected', '.gitkeep'),
+        path.join(getPlanningRoot(cwd), 'ideas', 'done', '.gitkeep'),
+        path.join(getPlanningRoot(cwd), 'specs', '.gitkeep'),
+        path.join(getPlanningRoot(cwd), 'docs', 'product', '.gitkeep'),
+      ];
+      for (const gk of dirsToKeep) {
+        if (!fs.existsSync(gk)) {
+          fs.writeFileSync(gk, '', 'utf-8');
+        }
+      }
+      error('Product already initialized. Use /dgs:progress to see status.');
+    }
+  }
+
+  // ── Shared scaffolding (layout-aware via getPlanningRoot) ─────────────────
+
+  // Ensure planning root exists (for standard layout creates .planning/; for root it's cwd)
+  fs.mkdirSync(getPlanningRoot(cwd), { recursive: true });
+
+  // Create ideas, specs, and docs directories for v3.0 features
+  const ideasStates = ['pending', 'rejected', 'done'];
+  for (const state of ideasStates) {
+    fs.mkdirSync(path.join(getPlanningRoot(cwd), 'ideas', state), { recursive: true });
+  }
+  fs.mkdirSync(path.join(getPlanningRoot(cwd), 'specs'), { recursive: true });
+  fs.mkdirSync(path.join(getPlanningRoot(cwd), 'docs', 'product'), { recursive: true });
+
+  // Add .gitkeep files to empty directories so they survive git commit
+  const gitkeepPaths = [
+    path.join(getPlanningRoot(cwd), 'ideas', 'pending', '.gitkeep'),
+    path.join(getPlanningRoot(cwd), 'ideas', 'rejected', '.gitkeep'),
+    path.join(getPlanningRoot(cwd), 'ideas', 'done', '.gitkeep'),
+    path.join(getPlanningRoot(cwd), 'specs', '.gitkeep'),
+    path.join(getPlanningRoot(cwd), 'docs', 'product', '.gitkeep'),
+  ];
+  for (const gk of gitkeepPaths) {
+    if (!fs.existsSync(gk)) {
+      fs.writeFileSync(gk, '', 'utf-8');
+    }
+  }
+
+  // Scaffold review-keys.json with empty template
+  const reviewKeysPath = path.join(getPlanningRoot(cwd), 'review-keys.json');
+  if (!fs.existsSync(reviewKeysPath)) {
+    const reviewKeysTemplate = {
+      openai: { api_key: "", model: "gpt-5-mini" },
+      gemini: { api_key: "", model: "gemini-2.5-flash" },
+      max_rounds: 3
+    };
+    fs.writeFileSync(reviewKeysPath, JSON.stringify(reviewKeysTemplate, null, 2), 'utf-8');
+  }
+
+  // Discover repos (local children + sibling repos)
+  const discoveredRepos = discoverRepos(cwd);
+  const siblingRepos = discoverSiblingRepos(cwd);
+  const allRepos = [...discoveredRepos, ...siblingRepos];
+
+  // Derive product name
+  const productName = options.productName || path.basename(cwd);
+
+  // Check if .git/ exists at cwd root
+  const needsGitInit = !fs.existsSync(path.join(cwd, '.git'));
+
+  // Write REPOS.md
+  writeReposMd(cwd, allRepos);
+
+  // Write PROJECTS.md (empty — no projects yet)
+  writeProjectsMd(cwd, []);
+
+  if (isRootMode) {
+    // Root-mode: generate .gitignore for root-layout repo
+    generateRootGitignore(cwd);
+
+    // Update config with product_name (config already exists from config-first step)
+    writeConfigField(cwd, 'product_name', productName);
+
+    output({
+      initialized: true,
+      layout: 'root',
+      product_name: productName,
+      repos_found: allRepos.length,
+      repos: allRepos,
+      needs_git_init: needsGitInit,
+      ideas_dirs_created: true,
+      specs_dir_created: true,
+      docs_dir_created: true,
+      files_created: ['dgs.config.json', 'REPOS.md', 'PROJECTS.md', 'ideas/', 'specs/', 'docs/', '.gitignore', 'review-keys.json'],
+    }, raw);
+  } else {
+    // Standard layout: sync .gitignore for local repo paths
+    const localPaths = allRepos.map(r => r.path).filter(p => p.startsWith('./'));
+    if (localPaths.length > 0) {
+      syncGitignore(cwd, localPaths);
+    }
+
+    // Update config with product_name
+    writeConfigField(cwd, 'product_name', productName);
+
+    output({
+      initialized: true,
+      layout: 'dotplanning',
+      product_name: productName,
+      repos_found: allRepos.length,
+      repos: allRepos,
+      needs_git_init: needsGitInit,
+      gitignore_synced: localPaths.length > 0,
+      ideas_dirs_created: true,
+      specs_dir_created: true,
+      docs_dir_created: true,
+      files_created: ['.planning/', '.planning/REPOS.md', '.planning/PROJECTS.md', '.planning/ideas/', '.planning/specs/', '.planning/docs/', '.planning/review-keys.json'],
+    }, raw);
+  }
+}
+
+/**
+ * Scan plan files for <repos> tags and check against registered repos.
+ * Detects unknown repos per REPO-06.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phaseDir - Phase directory to scan (relative to cwd)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposScanTags(cwd, phaseDir, raw) {
+  if (!phaseDir) {
+    error('Usage: repos scan-tags <phase-dir>');
+  }
+
+  const dir = path.join(cwd, phaseDir);
+  let planFiles;
+  try {
+    planFiles = fs.readdirSync(dir).filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+  } catch {
+    error(`Cannot read phase directory: ${phaseDir}`);
+  }
+
+  // Collect all repo names from <repos> tags
+  const allReferenced = new Set();
+  for (const planFile of planFiles) {
+    const content = safeReadFile(path.join(dir, planFile));
+    if (!content) continue;
+
+    const matches = content.match(/<repos>([^<]+)<\/repos>/g);
+    if (!matches) continue;
+
+    for (const match of matches) {
+      const inner = match.replace(/<\/?repos>/g, '');
+      const names = inner.split(',').map(n => n.trim()).filter(n => n);
+      names.forEach(n => allReferenced.add(n));
+    }
+  }
+
+  const referenced = Array.from(allReferenced);
+
+  // Check against REPOS.md
+  const existing = parseReposMd(cwd);
+  const knownNames = existing ? new Set(existing.repos.map(r => r.name)) : new Set();
+
+  const known = referenced.filter(n => knownNames.has(n));
+  const unknown = referenced.filter(n => !knownNames.has(n));
+
+  output({ referenced, known, unknown }, raw);
+}
+
+/**
+ * CLI: Auto-populate <repos> tags in a plan file from <files> paths.
+ * Reads REPOS.md, reads plan file, runs autoPopulateReposTags, writes result.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} planFile - Path to plan file (relative to cwd)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposAutoPopulate(cwd, planFile, raw) {
+  if (!planFile) {
+    error('Usage: repos auto-populate <plan-file>');
+  }
+  const fullPath = path.join(cwd, planFile);
+  let content;
+  try {
+    content = fs.readFileSync(fullPath, 'utf-8');
+  } catch {
+    error(`Cannot read plan file: ${planFile}`);
+  }
+  const reposData = parseReposMd(cwd);
+  if (!reposData || reposData.repos.length === 0) {
+    error('No repos found in REPOS.md. Run /dgs:init-product first.');
+  }
+  const result = autoPopulateReposTags(content, reposData.repos);
+  // Write updated content back to file
+  fs.writeFileSync(fullPath, result.content, 'utf-8');
+  output({ updated: true, file: planFile, warnings: result.warnings }, raw);
+}
+
+/**
+ * CLI: Validate <repos>/<files> consistency in a plan file.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} planFile - Path to plan file (relative to cwd)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdReposValidateConsistency(cwd, planFile, raw) {
+  if (!planFile) {
+    error('Usage: repos validate-consistency <plan-file>');
+  }
+  const fullPath = path.join(cwd, planFile);
+  let content;
+  try {
+    content = fs.readFileSync(fullPath, 'utf-8');
+  } catch {
+    error(`Cannot read plan file: ${planFile}`);
+  }
+  const reposData = parseReposMd(cwd);
+  if (!reposData || reposData.repos.length === 0) {
+    error('No repos found in REPOS.md. Run /dgs:init-product first.');
+  }
+  const result = validateReposConsistency(content, reposData.repos);
+  output(result, raw);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  parseReposMd,
+  writeReposMd,
+  validateReposMdEager,
+  resolveFileToRepo,
+  discoverRepos,
+  discoverSiblingRepos,
+  syncGitignore,
+  validateRepoPaths,
+  hasPathConflict,
+  writeProjectsMd,
+  autoPopulateReposTags,
+  validateReposConsistency,
+  cmdDetectLayout,
+  generateRootGitignore,
+  cmdReposList,
+  cmdReposAdd,
+  cmdReposRemove,
+  cmdReposValidate,
+  cmdReposResolve,
+  cmdReposInitProduct,
+  cmdReposScanTags,
+  cmdReposAutoPopulate,
+  cmdReposValidateConsistency,
+};