code-as-plan 2.0.0

package/cap/bin/lib/config.cjs

@@ -0,0 +1,466 @@
+/**
+ * Config — Planning config CRUD operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, planningRoot } = require('./core.cjs');
+const {
+  VALID_PROFILES,
+  getAgentToModelMapForProfile,
+  formatAgentToModelMapAsTable,
+} = require('./model-profiles.cjs');
+
+const VALID_CONFIG_KEYS = new Set([
+  'mode', 'granularity', 'parallelization', 'commit_docs', 'model_profile',
+  'search_gitignored', 'brave_search', 'firecrawl', 'exa_search',
+  'workflow.research', 'workflow.plan_check', 'workflow.verifier',
+  'workflow.nyquist_validation', 'workflow.ui_phase', 'workflow.ui_safety_gate',
+  'workflow.auto_advance', 'workflow.node_repair', 'workflow.node_repair_budget',
+  'workflow.text_mode',
+  'workflow.research_before_questions',
+  'workflow.discuss_mode',
+  'workflow.skip_discuss',
+  'workflow._auto_chain_active',
+  'git.branching_strategy', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
+  'planning.commit_docs', 'planning.search_gitignored',
+  'hooks.context_warnings',
+  'arc.enabled', 'arc.tag_prefix', 'arc.comment_anchors',
+  'phase_modes.default', 'default_phase_mode',
+]);
+
+/**
+ * Check whether a config key path is valid.
+ * Supports exact matches from VALID_CONFIG_KEYS plus dynamic patterns
+ * like `agent_skills.<agent-type>` where the sub-key is freeform.
+ */
+function isValidConfigKey(keyPath) {
+  if (VALID_CONFIG_KEYS.has(keyPath)) return true;
+  // Allow agent_skills.<agent-type> with any agent type string
+  if (/^agent_skills\.[a-zA-Z0-9_-]+$/.test(keyPath)) return true;
+  // Allow phase_modes.<number> for per-phase mode overrides
+  if (/^phase_modes\.\d+$/.test(keyPath)) return true;
+  return false;
+}
+
+const CONFIG_KEY_SUGGESTIONS = {
+  'workflow.nyquist_validation_enabled': 'workflow.nyquist_validation',
+  'agents.nyquist_validation_enabled': 'workflow.nyquist_validation',
+  'nyquist.validation_enabled': 'workflow.nyquist_validation',
+  'hooks.research_questions': 'workflow.research_before_questions',
+  'workflow.research_questions': 'workflow.research_before_questions',
+};
+
+function validateKnownConfigKeyPath(keyPath) {
+  const suggested = CONFIG_KEY_SUGGESTIONS[keyPath];
+  if (suggested) {
+    error(`Unknown config key: ${keyPath}. Did you mean ${suggested}?`);
+  }
+}
+
+/**
+ * Build a fully-materialized config object for a new project.
+ *
+ * Merges (increasing priority):
+ *   1. Hardcoded defaults — every key that loadConfig() resolves, plus mode/granularity
+ *   2. User-level defaults from ~/.gsd/defaults.json (if present)
+ *   3. userChoices — the settings the user explicitly selected during /gsd:new-project
+ *
+ * Uses the canonical `git` namespace for branching keys (consistent with VALID_CONFIG_KEYS
+ * and the settings workflow). loadConfig() handles both flat and nested formats, so this
+ * is backward-compatible with existing projects that have flat keys.
+ *
+ * Returns a plain object — does NOT write any files.
+ */
+function buildNewProjectConfig(userChoices) {
+  const choices = userChoices || {};
+  const homedir = require('os').homedir();
+
+  // Detect API key availability
+  const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key');
+  const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile));
+  const firecrawlKeyFile = path.join(homedir, '.gsd', 'firecrawl_api_key');
+  const hasFirecrawl = !!(process.env.FIRECRAWL_API_KEY || fs.existsSync(firecrawlKeyFile));
+  const exaKeyFile = path.join(homedir, '.gsd', 'exa_api_key');
+  const hasExaSearch = !!(process.env.EXA_API_KEY || fs.existsSync(exaKeyFile));
+
+  // Load user-level defaults from ~/.gsd/defaults.json if available
+  const globalDefaultsPath = path.join(homedir, '.gsd', 'defaults.json');
+  let userDefaults = {};
+  try {
+    if (fs.existsSync(globalDefaultsPath)) {
+      userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8'));
+      // Migrate deprecated "depth" key to "granularity"
+      if ('depth' in userDefaults && !('granularity' in userDefaults)) {
+        const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
+        userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth;
+        delete userDefaults.depth;
+        try {
+          fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8');
+        } catch { /* intentionally empty */ }
+      }
+    }
+  } catch {
+    // Ignore malformed global defaults
+  }
+
+  const hardcoded = {
+    model_profile: 'balanced',
+    commit_docs: true,
+    parallelization: true,
+    search_gitignored: false,
+    brave_search: hasBraveSearch,
+    firecrawl: hasFirecrawl,
+    exa_search: hasExaSearch,
+    git: {
+      branching_strategy: 'none',
+      phase_branch_template: 'gsd/phase-{phase}-{slug}',
+      milestone_branch_template: 'gsd/{milestone}-{slug}',
+      quick_branch_template: null,
+    },
+    workflow: {
+      research: true,
+      plan_check: true,
+      verifier: true,
+      nyquist_validation: true,
+      auto_advance: false,
+      node_repair: true,
+      node_repair_budget: 2,
+      ui_phase: true,
+      ui_safety_gate: true,
+      text_mode: false,
+      research_before_questions: false,
+      discuss_mode: 'discuss',
+      skip_discuss: false,
+    },
+    hooks: {
+      context_warnings: true,
+    },
+    agent_skills: {},
+    arc: {
+      enabled: true,
+      tag_prefix: '@gsd-',
+      comment_anchors: ['//', '#', '/*', '--'],
+    },
+    phase_modes: {},
+    default_phase_mode: 'plan-first',
+  };
+
+  // Three-level deep merge: hardcoded <- userDefaults <- choices
+  return {
+    ...hardcoded,
+    ...userDefaults,
+    ...choices,
+    git: {
+      ...hardcoded.git,
+      ...(userDefaults.git || {}),
+      ...(choices.git || {}),
+    },
+    workflow: {
+      ...hardcoded.workflow,
+      ...(userDefaults.workflow || {}),
+      ...(choices.workflow || {}),
+    },
+    hooks: {
+      ...hardcoded.hooks,
+      ...(userDefaults.hooks || {}),
+      ...(choices.hooks || {}),
+    },
+    agent_skills: {
+      ...hardcoded.agent_skills,
+      ...(userDefaults.agent_skills || {}),
+      ...(choices.agent_skills || {}),
+    },
+    arc: {
+      ...hardcoded.arc,
+      ...(userDefaults.arc || {}),
+      ...(choices.arc || {}),
+    },
+    phase_modes: {
+      ...hardcoded.phase_modes,
+      ...(userDefaults.phase_modes || {}),
+      ...(choices.phase_modes || {}),
+    },
+    default_phase_mode: choices.default_phase_mode || userDefaults.default_phase_mode || hardcoded.default_phase_mode,
+  };
+}
+
+/**
+ * Command: create a fully-materialized .planning/config.json for a new project.
+ *
+ * Accepts user-chosen settings as a JSON string (the keys the user explicitly
+ * configured during /gsd:new-project). All remaining keys are filled from
+ * hardcoded defaults and optional ~/.gsd/defaults.json.
+ *
+ * Idempotent: if config.json already exists, returns { created: false }.
+ */
+function cmdConfigNewProject(cwd, choicesJson, raw) {
+  const planningBase = planningRoot(cwd);
+  const configPath = path.join(planningBase, 'config.json');
+
+  // Idempotent: don't overwrite existing config
+  if (fs.existsSync(configPath)) {
+    output({ created: false, reason: 'already_exists' }, raw, 'exists');
+    return;
+  }
+
+  // Parse user choices
+  let userChoices = {};
+  if (choicesJson && choicesJson.trim() !== '') {
+    try {
+      userChoices = JSON.parse(choicesJson);
+    } catch (err) {
+      error('Invalid JSON for config-new-project: ' + err.message);
+    }
+  }
+
+  // Ensure .planning directory exists
+  try {
+    if (!fs.existsSync(planningBase)) {
+      fs.mkdirSync(planningBase, { recursive: true });
+    }
+  } catch (err) {
+    error('Failed to create .planning directory: ' + err.message);
+  }
+
+  const config = buildNewProjectConfig(userChoices);
+
+  try {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    output({ created: true, path: '.planning/config.json' }, raw, 'created');
+  } catch (err) {
+    error('Failed to write config.json: ' + err.message);
+  }
+}
+
+/**
+ * Ensures the config file exists (creates it if needed).
+ *
+ * Does not call `output()`, so can be used as one step in a command without triggering `exit(0)` in
+ * the happy path. But note that `error()` will still `exit(1)` out of the process.
+ */
+function ensureConfigFile(cwd) {
+  const planningBase = planningRoot(cwd);
+  const configPath = path.join(planningBase, 'config.json');
+
+  // Ensure .planning directory exists
+  try {
+    if (!fs.existsSync(planningBase)) {
+      fs.mkdirSync(planningBase, { recursive: true });
+    }
+  } catch (err) {
+    error('Failed to create .planning directory: ' + err.message);
+  }
+
+  // Check if config already exists
+  if (fs.existsSync(configPath)) {
+    return { created: false, reason: 'already_exists' };
+  }
+
+  const config = buildNewProjectConfig({});
+
+  try {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    return { created: true, path: '.planning/config.json' };
+  } catch (err) {
+    error('Failed to create config.json: ' + err.message);
+  }
+}
+
+/**
+ * Command to ensure the config file exists (creates it if needed).
+ *
+ * Note that this exits the process (via `output()`) even in the happy path; use
+ * `ensureConfigFile()` directly if you need to avoid this.
+ */
+function cmdConfigEnsureSection(cwd, raw) {
+  const ensureConfigFileResult = ensureConfigFile(cwd);
+  if (ensureConfigFileResult.created) {
+    output(ensureConfigFileResult, raw, 'created');
+  } else {
+    output(ensureConfigFileResult, raw, 'exists');
+  }
+}
+
+/**
+ * Sets a value in the config file, allowing nested values via dot notation (e.g.,
+ * "workflow.research").
+ *
+ * Does not call `output()`, so can be used as one step in a command without triggering `exit(0)` in
+ * the happy path. But note that `error()` will still `exit(1)` out of the process.
+ */
+function setConfigValue(cwd, keyPath, parsedValue) {
+  const configPath = path.join(planningRoot(cwd), 'config.json');
+
+  // Load existing config or start with empty object
+  let config = {};
+  try {
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+  } catch (err) {
+    error('Failed to read config.json: ' + err.message);
+  }
+
+  // Set nested value using dot notation (e.g., "workflow.research")
+  const keys = keyPath.split('.');
+  let current = config;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (current[key] === undefined || typeof current[key] !== 'object') {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  const previousValue = current[keys[keys.length - 1]]; // Capture previous value before overwriting
+  current[keys[keys.length - 1]] = parsedValue;
+
+  // Write back
+  try {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    return { updated: true, key: keyPath, value: parsedValue, previousValue };
+  } catch (err) {
+    error('Failed to write config.json: ' + err.message);
+  }
+}
+
+/**
+ * Command to set a value in the config file, allowing nested values via dot notation (e.g.,
+ * "workflow.research").
+ *
+ * Note that this exits the process (via `output()`) even in the happy path; use `setConfigValue()`
+ * directly if you need to avoid this.
+ */
+function cmdConfigSet(cwd, keyPath, value, raw) {
+  if (!keyPath) {
+    error('Usage: config-set <key.path> <value>');
+  }
+
+  validateKnownConfigKeyPath(keyPath);
+
+  if (!isValidConfigKey(keyPath)) {
+    error(`Unknown config key: "${keyPath}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>`);
+  }
+
+  // Parse value (handle booleans, numbers, and JSON arrays/objects)
+  let parsedValue = value;
+  if (value === 'true') parsedValue = true;
+  else if (value === 'false') parsedValue = false;
+  else if (!isNaN(value) && value !== '') parsedValue = Number(value);
+  else if (typeof value === 'string' && (value.startsWith('[') || value.startsWith('{'))) {
+    try { parsedValue = JSON.parse(value); } catch { /* keep as string */ }
+  }
+
+  const setConfigValueResult = setConfigValue(cwd, keyPath, parsedValue);
+  output(setConfigValueResult, raw, `${keyPath}=${parsedValue}`);
+}
+
+function cmdConfigGet(cwd, keyPath, raw) {
+  const configPath = path.join(planningRoot(cwd), 'config.json');
+
+  if (!keyPath) {
+    error('Usage: config-get <key.path>');
+  }
+
+  let config = {};
+  try {
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } else {
+      error('No config.json found at ' + configPath);
+    }
+  } catch (err) {
+    if (err.message.startsWith('No config.json')) throw err;
+    error('Failed to read config.json: ' + err.message);
+  }
+
+  // Traverse dot-notation path (e.g., "workflow.auto_advance")
+  const keys = keyPath.split('.');
+  let current = config;
+  for (const key of keys) {
+    if (current === undefined || current === null || typeof current !== 'object') {
+      error(`Key not found: ${keyPath}`);
+    }
+    current = current[key];
+  }
+
+  if (current === undefined) {
+    error(`Key not found: ${keyPath}`);
+  }
+
+  output(current, raw, String(current));
+}
+
+/**
+ * Command to set the model profile in the config file.
+ *
+ * Note that this exits the process (via `output()`) even in the happy path.
+ */
+function cmdConfigSetModelProfile(cwd, profile, raw) {
+  if (!profile) {
+    error(`Usage: config-set-model-profile <${VALID_PROFILES.join('|')}>`);
+  }
+
+  const normalizedProfile = profile.toLowerCase().trim();
+  if (!VALID_PROFILES.includes(normalizedProfile)) {
+    error(`Invalid profile '${profile}'. Valid profiles: ${VALID_PROFILES.join(', ')}`);
+  }
+
+  // Ensure config exists (create if needed)
+  ensureConfigFile(cwd);
+
+  // Set the model profile in the config
+  const { previousValue } = setConfigValue(cwd, 'model_profile', normalizedProfile, raw);
+  const previousProfile = previousValue || 'balanced';
+
+  // Build result value / message and return
+  const agentToModelMap = getAgentToModelMapForProfile(normalizedProfile);
+  const result = {
+    updated: true,
+    profile: normalizedProfile,
+    previousProfile,
+    agentToModelMap,
+  };
+  const rawValue = getCmdConfigSetModelProfileResultMessage(
+    normalizedProfile,
+    previousProfile,
+    agentToModelMap
+  );
+  output(result, raw, rawValue);
+}
+
+/**
+ * Returns the message to display for the result of the `config-set-model-profile` command when
+ * displaying raw output.
+ */
+function getCmdConfigSetModelProfileResultMessage(
+  normalizedProfile,
+  previousProfile,
+  agentToModelMap
+) {
+  const agentToModelTable = formatAgentToModelMapAsTable(agentToModelMap);
+  const didChange = previousProfile !== normalizedProfile;
+  const paragraphs = didChange
+    ? [
+        `✓ Model profile set to: ${normalizedProfile} (was: ${previousProfile})`,
+        'Agents will now use:',
+        agentToModelTable,
+        'Next spawned agents will use the new profile.',
+      ]
+    : [
+        `✓ Model profile is already set to: ${normalizedProfile}`,
+        'Agents are using:',
+        agentToModelTable,
+      ];
+  return paragraphs.join('\n\n');
+}
+
+module.exports = {
+  buildNewProjectConfig,
+  cmdConfigEnsureSection,
+  cmdConfigSet,
+  cmdConfigGet,
+  cmdConfigSetModelProfile,
+  cmdConfigNewProject,
+  setConfigValue,
+};

package/cap/bin/lib/convention-reader.cjs

@@ -0,0 +1,180 @@
+// @gsd-context(phase:11) Convention reader utility -- discovers existing project conventions for architecture mode
+// @gsd-decision Implemented as a standalone CJS module (not inline in the agent) so it can be tested independently
+// @gsd-ref(ref:ARCH-03) gsd-prototyper reads existing project conventions before generating skeleton
+// @gsd-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path)
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// @gsd-api readProjectConventions(projectRoot) -- returns ConventionReport object describing discovered patterns
+// @gsd-pattern Convention reader returns a structured report that the agent prompt can serialize into context
+
+/**
+ * @typedef {Object} ConventionReport
+ * @property {string} moduleType - 'esm' | 'cjs' | 'unknown'
+ * @property {string} namingConvention - 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case' | 'unknown'
+ * @property {string} testPattern - 'colocated' | 'separate-dir' | 'unknown'
+ * @property {string|null} testRunner - detected test runner name or null
+ * @property {Object} pathAliases - e.g., { '@/*': ['src/*'] }
+ * @property {string|null} buildTool - detected build tool or null
+ * @property {string|null} linter - detected linter or null
+ * @property {string[]} existingDirs - list of existing directories (max depth 3)
+ * @property {Object} packageJson - parsed package.json or null
+ */
+
+/**
+ * Reads existing project conventions from config files and directory structure.
+ * Used by gsd-prototyper in architecture mode to match generated skeleton
+ * to the project's established patterns.
+ *
+ * @param {string} projectRoot - absolute path to project root
+ * @returns {ConventionReport}
+ */
+function readProjectConventions(projectRoot) {
+  // @gsd-todo(ref:AC-3) Implement full convention discovery: package.json parsing, tsconfig reading, directory pattern detection, linter config extraction
+  const report = {
+    moduleType: 'unknown',
+    namingConvention: 'unknown',
+    testPattern: 'unknown',
+    testRunner: null,
+    pathAliases: {},
+    buildTool: null,
+    linter: null,
+    existingDirs: [],
+    packageJson: null,
+  };
+
+  // --- package.json detection ---
+  // @gsd-context Reads package.json for module type, naming conventions, and dependency-based framework detection
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      report.packageJson = pkg;
+      report.moduleType = pkg.type === 'module' ? 'esm' : 'cjs';
+
+      // @gsd-decision Detect test runner from devDependencies keys rather than config files -- faster and covers most cases
+      if (pkg.devDependencies) {
+        if (pkg.devDependencies.vitest) report.testRunner = 'vitest';
+        else if (pkg.devDependencies.jest) report.testRunner = 'jest';
+        else if (pkg.devDependencies.mocha) report.testRunner = 'mocha';
+        else if (pkg.devDependencies.ava) report.testRunner = 'ava';
+      }
+
+      // @gsd-decision Detect build tool from devDependencies -- covers esbuild, webpack, vite, rollup
+      if (pkg.devDependencies) {
+        if (pkg.devDependencies.esbuild) report.buildTool = 'esbuild';
+        else if (pkg.devDependencies.vite) report.buildTool = 'vite';
+        else if (pkg.devDependencies.webpack) report.buildTool = 'webpack';
+        else if (pkg.devDependencies.rollup) report.buildTool = 'rollup';
+      }
+    } catch (_e) {
+      // @gsd-risk Malformed package.json silently ignored -- could produce incorrect convention report
+    }
+  }
+
+  // --- tsconfig.json / jsconfig.json detection ---
+  // @gsd-context Reads TypeScript/JavaScript config for path aliases and module resolution
+  const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+  const jsconfigPath = path.join(projectRoot, 'jsconfig.json');
+  const configPath = fs.existsSync(tsconfigPath) ? tsconfigPath : (fs.existsSync(jsconfigPath) ? jsconfigPath : null);
+
+  if (configPath) {
+    try {
+      // Strip JS-style comments (// and /* */) before parsing — handles JSONC tsconfig files
+      let raw = fs.readFileSync(configPath, 'utf8');
+      raw = raw.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+      const config = JSON.parse(raw);
+      if (config.compilerOptions && config.compilerOptions.paths) {
+        report.pathAliases = config.compilerOptions.paths;
+      }
+    } catch (_e) {
+      // Malformed config silently ignored
+    }
+  }
+
+  // --- Directory structure detection ---
+  // @gsd-context Reads directory names to detect naming convention (kebab-case vs camelCase etc.)
+  report.existingDirs = discoverDirectories(projectRoot, 3);
+  report.namingConvention = detectNamingConvention(report.existingDirs);
+
+  // --- Test pattern detection ---
+  // @gsd-decision Check for tests/ or __tests__/ directory first, then fall back to checking for colocated .test. files
+  const hasTestsDir = report.existingDirs.some(d => d === 'tests' || d === '__tests__' || d.endsWith('/tests') || d.endsWith('/__tests__'));
+  if (hasTestsDir) {
+    report.testPattern = 'separate-dir';
+  }
+  // @gsd-todo Detect colocated test pattern by scanning for *.test.* files alongside source files
+
+  // --- Linter detection ---
+  // @gsd-context Checks for linter config files to match code style in generated skeleton
+  const linterFiles = ['.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.cjs', 'biome.json', 'biome.jsonc'];
+  for (const f of linterFiles) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      report.linter = f.includes('biome') ? 'biome' : 'eslint';
+      break;
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Recursively discovers directories up to maxDepth.
+ * @param {string} dir
+ * @param {number} maxDepth
+ * @param {number} [currentDepth=0]
+ * @returns {string[]}
+ */
+function discoverDirectories(dir, maxDepth, currentDepth = 0) {
+  // @gsd-constraint Uses readdirSync (not glob) per project zero-dep constraint
+  if (currentDepth >= maxDepth) return [];
+
+  const results = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.planning') continue;
+
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(dir, fullPath);
+      results.push(relativePath);
+      const children = discoverDirectories(fullPath, maxDepth, currentDepth + 1);
+      results.push(...children.map(c => path.join(entry.name, c)));
+    }
+  } catch (_e) {
+    // Permission errors etc.
+  }
+
+  return results;
+}
+
+/**
+ * Detects naming convention from directory names.
+ * @param {string[]} dirs
+ * @returns {string}
+ */
+function detectNamingConvention(dirs) {
+  // @gsd-decision Simple heuristic: check if majority of directory names match a pattern
+  // @gsd-risk Heuristic may misclassify projects with mixed naming -- returns 'unknown' when ambiguous
+  const leafNames = dirs.map(d => path.basename(d)).filter(n => n.length > 1);
+  if (leafNames.length === 0) return 'unknown';
+
+  const kebab = leafNames.filter(n => /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/.test(n)).length;
+  const camel = leafNames.filter(n => /^[a-z][a-zA-Z0-9]+$/.test(n) && /[A-Z]/.test(n)).length;
+  const pascal = leafNames.filter(n => /^[A-Z][a-zA-Z0-9]+$/.test(n)).length;
+  const snake = leafNames.filter(n => /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/.test(n)).length;
+
+  const max = Math.max(kebab, camel, pascal, snake);
+  if (max === 0) return 'unknown';
+  if (kebab === max) return 'kebab-case';
+  if (camel === max) return 'camelCase';
+  if (pascal === max) return 'PascalCase';
+  if (snake === max) return 'snake_case';
+  return 'unknown';
+}
+
+module.exports = { readProjectConventions, discoverDirectories, detectNamingConvention };