@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/bin/lib/commands.cjs

@@ -3,8 +3,9 @@
  */
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
-const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, resolveModelInternal, stripShippedMilestones, extractCurrentMilestone, planningDir, planningPaths, toPosixPath, output, error, findPhaseInternal, extractOneLinerFromBody, getRoadmapPhaseInternal } = require('./core.cjs');
+const { execGit, platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
+const { loadConfig, isGitIgnored, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, resolveModelInternal, resolveReasoningEffortInternal, stripShippedMilestones, extractCurrentMilestone, toPosixPath, output, error, findPhaseInternal, extractOneLinerFromBody, getRoadmapPhaseInternal } = require('./core.cjs');
+const { planningDir, planningPaths } = require('./planning-workspace.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
@@ -22,7 +23,7 @@ function determinePhaseStatus(plans, summaries, phaseDir, defaultPending) {
     const files = fs.readdirSync(phaseDir);
     const verificationFile = files.find(f => f === 'VERIFICATION.md' || f.endsWith('-VERIFICATION.md'));
     if (verificationFile) {
-      const content = fs.readFileSync(path.join(phaseDir, verificationFile), 'utf-8');
+      const content = platformReadSync(path.join(phaseDir, verificationFile)) || '';
       if (/status:\s*passed/i.test(content)) return 'Complete';
       if (/status:\s*human_needed/i.test(content)) return 'Needs Review';
       if (/status:\s*gaps_found/i.test(content)) return 'Executed';
@@ -80,26 +81,25 @@ function cmdListTodos(cwd, area, raw) {
     const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
 
     for (const file of files) {
-      try {
-        const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8');
-        const createdMatch = content.match(/^created:\s*(.+)$/m);
-        const titleMatch = content.match(/^title:\s*(.+)$/m);
-        const areaMatch = content.match(/^area:\s*(.+)$/m);
-
-        const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
-
-        // Apply area filter if specified
-        if (area && todoArea !== area) continue;
-
-        count++;
-        todos.push({
-          file,
-          created: createdMatch ? createdMatch[1].trim() : 'unknown',
-          title: titleMatch ? titleMatch[1].trim() : 'Untitled',
-          area: todoArea,
-          path: toPosixPath(path.relative(cwd, path.join(pendingDir, file))),
-        });
-      } catch { /* intentionally empty */ }
+      const content = platformReadSync(path.join(pendingDir, file));
+      if (content === null) continue;
+      const createdMatch = content.match(/^created:\s*(.+)$/m);
+      const titleMatch = content.match(/^title:\s*(.+)$/m);
+      const areaMatch = content.match(/^area:\s*(.+)$/m);
+
+      const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
+
+      // Apply area filter if specified
+      if (area && todoArea !== area) continue;
+
+      count++;
+      todos.push({
+        file,
+        created: createdMatch ? createdMatch[1].trim() : 'unknown',
+        title: titleMatch ? titleMatch[1].trim() : 'Untitled',
+        area: todoArea,
+        path: toPosixPath(path.relative(cwd, path.join(pendingDir, file))),
+      });
     }
   } catch { /* intentionally empty */ }
 
@@ -167,8 +167,9 @@ function cmdHistoryDigest(cwd, raw) {
       const summaries = fs.readdirSync(dirPath).filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
 
       for (const summary of summaries) {
+        const content = platformReadSync(path.join(dirPath, summary));
+        if (content === null) continue;
         try {
-          const content = fs.readFileSync(path.join(dirPath, summary), 'utf-8');
           const fm = extractFrontmatter(content);
 
           const phaseNum = fm.phase || dir.split('-')[0];
@@ -239,11 +240,13 @@ function cmdResolveModel(cwd, agentType, raw) {
   const config = loadConfig(cwd);
   const profile = config.model_profile || 'balanced';
   const model = resolveModelInternal(cwd, agentType);
+  const reasoningEffort = resolveReasoningEffortInternal(cwd, agentType);
 
   const agentModels = MODEL_PROFILES[agentType];
   const result = agentModels
     ? { model, profile }
     : { model, profile, unknown_agent: true };
+  if (reasoningEffort) result.reasoning_effort = reasoningEffort;
   output(result, raw, model);
 }
 
@@ -301,12 +304,12 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
       }
     }
     if (branchName) {
-      const currentBranch = execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+      const currentBranch = execGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
       if (currentBranch.exitCode === 0 && currentBranch.stdout.trim() !== branchName) {
         // Create branch if it doesn't exist, or switch to it if it does
-        const create = execGit(cwd, ['checkout', '-b', branchName]);
+        const create = execGit(['checkout', '-b', branchName], { cwd });
         if (create.exitCode !== 0) {
-          execGit(cwd, ['checkout', branchName]);
+          execGit(['checkout', branchName], { cwd });
         }
       }
     }
@@ -326,29 +329,34 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
       }
       // Default mode (staging all of .planning/): stage the deletion so
       // removed planning files are not left dangling in the index.
-      execGit(cwd, ['rm', '--cached', '--ignore-unmatch', file]);
+      execGit(['rm', '--cached', '--ignore-unmatch', file], { cwd });
     } else {
-      execGit(cwd, ['add', file]);
+      execGit(['add', file], { cwd });
     }
   }
 
   // Commit (--no-verify skips pre-commit hooks, used by parallel executor agents)
   const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message];
   if (noVerify) commitArgs.push('--no-verify');
-  const commitResult = execGit(cwd, commitArgs);
+  const commitResult = execGit(commitArgs, { cwd });
   if (commitResult.exitCode !== 0) {
     if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
       const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
       output(result, raw, 'nothing');
       return;
     }
-    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
-    output(result, raw, 'nothing');
+    const result = {
+      committed: false,
+      hash: null,
+      reason: 'commit_failed',
+      error: commitResult.stderr || commitResult.stdout,
+    };
+    output(result, raw, 'failed');
     return;
   }
 
   // Get short hash
-  const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  const hashResult = execGit(['rev-parse', '--short', 'HEAD'], { cwd });
   const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
   const result = { committed: true, hash, reason: 'committed' };
   output(result, raw, hash || 'committed');
@@ -394,11 +402,11 @@ function cmdCommitToSubrepo(cwd, message, files, raw) {
     // Stage files (strip sub-repo prefix for paths relative to that repo)
     for (const file of repoFiles) {
       const relativePath = file.slice(repo.length + 1);
-      execGit(repoCwd, ['add', relativePath]);
+      execGit(['add', relativePath], { cwd: repoCwd });
     }
 
     // Commit
-    const commitResult = execGit(repoCwd, ['commit', '-m', message]);
+    const commitResult = execGit(['commit', '-m', message], { cwd: repoCwd });
     if (commitResult.exitCode !== 0) {
       if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
         repos[repo] = { committed: false, hash: null, files: repoFiles, reason: 'nothing_to_commit' };
@@ -409,7 +417,7 @@ function cmdCommitToSubrepo(cwd, message, files, raw) {
     }
 
     // Get hash
-    const hashResult = execGit(repoCwd, ['rev-parse', '--short', 'HEAD']);
+    const hashResult = execGit(['rev-parse', '--short', 'HEAD'], { cwd: repoCwd });
     const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
     repos[repo] = { committed: true, hash, files: repoFiles };
   }
@@ -619,21 +627,20 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
   try {
     const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
     for (const file of files) {
-      try {
-        const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8');
-        const titleMatch = content.match(/^title:\s*(.+)$/m);
-        const areaMatch = content.match(/^area:\s*(.+)$/m);
-        const filesMatch = content.match(/^files:\s*(.+)$/m);
-        const body = content.replace(/^(title|area|files|created|priority):.*$/gm, '').trim();
-
-        todos.push({
-          file,
-          title: titleMatch ? titleMatch[1].trim() : 'Untitled',
-          area: areaMatch ? areaMatch[1].trim() : 'general',
-          files: filesMatch ? filesMatch[1].trim().split(/[,\s]+/).filter(Boolean) : [],
-          body: body.slice(0, 200), // first 200 chars for context
-        });
-      } catch {}
+      const content = platformReadSync(path.join(pendingDir, file));
+      if (content === null) continue;
+      const titleMatch = content.match(/^title:\s*(.+)$/m);
+      const areaMatch = content.match(/^area:\s*(.+)$/m);
+      const filesMatch = content.match(/^files:\s*(.+)$/m);
+      const body = content.replace(/^(title|area|files|created|priority):.*$/gm, '').trim();
+
+      todos.push({
+        file,
+        title: titleMatch ? titleMatch[1].trim() : 'Untitled',
+        area: areaMatch ? areaMatch[1].trim() : 'general',
+        files: filesMatch ? filesMatch[1].trim().split(/[,\s]+/).filter(Boolean) : [],
+        body: body.slice(0, 200), // first 200 chars for context
+      });
     }
   } catch {}
 
@@ -665,13 +672,12 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
       const phaseDir = path.join(cwd, phaseInfoDisk.directory);
       const planFiles = fs.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
       for (const pf of planFiles) {
-        try {
-          const planContent = fs.readFileSync(path.join(phaseDir, pf), 'utf-8');
-          const fmFiles = planContent.match(/files_modified:\s*\[([^\]]*)\]/);
-          if (fmFiles) {
-            phasePlans.push(...fmFiles[1].split(',').map(s => s.trim().replace(/['"]/g, '')).filter(Boolean));
-          }
-        } catch {}
+        const planContent = platformReadSync(path.join(phaseDir, pf));
+        if (planContent === null) continue;
+        const fmFiles = planContent.match(/files_modified:\s*\[([^\]]*)\]/);
+        if (fmFiles) {
+          phasePlans.push(...fmFiles[1].split(',').map(s => s.trim().replace(/['"]/g, '')).filter(Boolean));
+        }
       }
     } catch {}
   }
@@ -742,14 +748,14 @@ function cmdTodoComplete(cwd, filename, raw) {
   }
 
   // Ensure completed directory exists
-  fs.mkdirSync(completedDir, { recursive: true });
+  platformEnsureDir(completedDir);
 
   // Read, add completion timestamp, move
   let content = fs.readFileSync(sourcePath, 'utf-8');
   const today = new Date().toISOString().split('T')[0];
   content = `completed: ${today}\n` + content;
 
-  fs.writeFileSync(path.join(completedDir, filename), content, 'utf-8');
+  platformWriteSync(path.join(completedDir, filename), content);
   fs.unlinkSync(sourcePath);
 
   output({ completed: true, file: filename, date: today }, raw, 'completed');
@@ -773,7 +779,7 @@ function cmdScaffold(cwd, type, options, raw) {
   switch (type) {
     case 'context': {
       filePath = path.join(phaseDir, `${padded}-CONTEXT.md`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /sdd-discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /sdd:discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
       break;
     }
     case 'uat': {
@@ -791,11 +797,15 @@ function cmdScaffold(cwd, type, options, raw) {
         error('phase and name required for phase-dir scaffold');
       }
       const slug = generateSlugInternal(name);
-      const dirName = `${padded}-${slug}`;
+      // #3287: apply project_code prefix to stay consistent with phase.add/phase.insert
+      const scaffoldConfig = loadConfig(cwd);
+      const scaffoldProjectCode = scaffoldConfig.project_code || '';
+      const scaffoldPrefix = scaffoldProjectCode ? `${scaffoldProjectCode}-` : '';
+      const dirName = `${scaffoldPrefix}${padded}-${slug}`;
       const phasesParent = planningPaths(cwd).phases;
-      fs.mkdirSync(phasesParent, { recursive: true });
+      platformEnsureDir(phasesParent);
       const dirPath = path.join(phasesParent, dirName);
-      fs.mkdirSync(dirPath, { recursive: true });
+      platformEnsureDir(dirPath);
       output({ created: true, directory: toPosixPath(path.relative(cwd, dirPath)), path: dirPath }, raw, dirPath);
       return;
     }
@@ -808,7 +818,7 @@ function cmdScaffold(cwd, type, options, raw) {
     return;
   }
 
-  fs.writeFileSync(filePath, content, 'utf-8');
+  platformWriteSync(filePath, content);
   const relPath = toPosixPath(path.relative(cwd, filePath));
   output({ created: true, path: relPath }, raw, relPath);
 }
@@ -827,12 +837,15 @@ function cmdStats(cwd, format, raw) {
   let totalSummaries = 0;
 
   try {
-    const roadmapContent = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd);
+    const roadmapRaw = platformReadSync(roadmapPath);
+    if (roadmapRaw === null) throw new Error('roadmap missing');
+    const roadmapContent = extractCurrentMilestone(roadmapRaw, cwd);
     const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
     let match;
     while ((match = headingPattern.exec(roadmapContent)) !== null) {
-      phasesByNumber.set(match[1], {
-        number: match[1],
+      const key = normalizePhaseName(match[1]);
+      phasesByNumber.set(key, {
+        number: key,
         name: match[2].replace(/\(INSERTED\)/i, '').trim(),
         plans: 0,
         summaries: 0,
@@ -862,9 +875,10 @@ function cmdStats(cwd, format, raw) {
 
       const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, dir), 'Not Started');
 
-      const existing = phasesByNumber.get(phaseNum);
-      phasesByNumber.set(phaseNum, {
-        number: phaseNum,
+      const normalizedNum = normalizePhaseName(phaseNum);
+      const existing = phasesByNumber.get(normalizedNum);
+      phasesByNumber.set(normalizedNum, {
+        number: normalizedNum,
         name: existing?.name || phaseName,
         plans: (existing?.plans || 0) + plans,
         summaries: (existing?.summaries || 0) + summaries,
@@ -881,40 +895,36 @@ function cmdStats(cwd, format, raw) {
   // Requirements stats
   let requirementsTotal = 0;
   let requirementsComplete = 0;
-  try {
-    if (fs.existsSync(reqPath)) {
-      const reqContent = fs.readFileSync(reqPath, 'utf-8');
-      const checked = reqContent.match(/^- \[x\] \*\*/gm);
-      const unchecked = reqContent.match(/^- \[ \] \*\*/gm);
-      requirementsComplete = checked ? checked.length : 0;
-      requirementsTotal = requirementsComplete + (unchecked ? unchecked.length : 0);
-    }
-  } catch { /* intentionally empty */ }
+  const reqContent = platformReadSync(reqPath);
+  if (reqContent !== null) {
+    const checked = reqContent.match(/^- \[x\] \*\*/gm);
+    const unchecked = reqContent.match(/^- \[ \] \*\*/gm);
+    requirementsComplete = checked ? checked.length : 0;
+    requirementsTotal = requirementsComplete + (unchecked ? unchecked.length : 0);
+  }
 
   // Last activity from STATE.md
   let lastActivity = null;
-  try {
-    if (fs.existsSync(statePath)) {
-      const stateContent = fs.readFileSync(statePath, 'utf-8');
-      const activityMatch = stateContent.match(/^last_activity:\s*(.+)$/im)
-        || stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/i)
-        || stateContent.match(/^Last Activity:\s*(.+)$/im)
-        || stateContent.match(/^Last activity:\s*(.+)$/im);
-      if (activityMatch) lastActivity = activityMatch[1].trim();
-    }
-  } catch { /* intentionally empty */ }
+  const stateContent = platformReadSync(statePath);
+  if (stateContent !== null) {
+    const activityMatch = stateContent.match(/^last_activity:\s*(.+)$/im)
+      || stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/i)
+      || stateContent.match(/^Last Activity:\s*(.+)$/im)
+      || stateContent.match(/^Last activity:\s*(.+)$/im);
+    if (activityMatch) lastActivity = activityMatch[1].trim();
+  }
 
   // Git stats
   let gitCommits = 0;
   let gitFirstCommitDate = null;
-  const commitCount = execGit(cwd, ['rev-list', '--count', 'HEAD']);
+  const commitCount = execGit(['rev-list', '--count', 'HEAD'], { cwd });
   if (commitCount.exitCode === 0) {
     gitCommits = parseInt(commitCount.stdout, 10) || 0;
   }
-  const rootHash = execGit(cwd, ['rev-list', '--max-parents=0', 'HEAD']);
+  const rootHash = execGit(['rev-list', '--max-parents=0', 'HEAD'], { cwd });
   if (rootHash.exitCode === 0 && rootHash.stdout) {
     const firstCommit = rootHash.stdout.split('\n')[0].trim();
-    const firstDate = execGit(cwd, ['show', '-s', '--format=%as', firstCommit]);
+    const firstDate = execGit(['show', '-s', '--format=%as', firstCommit], { cwd });
     if (firstDate.exitCode === 0) {
       gitFirstCommitDate = firstDate.stdout || null;
     }
@@ -983,9 +993,9 @@ function cmdCheckCommit(cwd, raw) {
   }
 
   // commit_docs is false — check if any .planning/ files are staged
-  try {
-    const staged = execSync('git diff --cached --name-only', { cwd, encoding: 'utf-8' }).trim();
-    const planningFiles = staged.split('\n').filter(f => f.startsWith('.planning/') || f.startsWith('.planning\\'));
+  const stagedResult = execGit(['diff', '--cached', '--name-only'], { cwd });
+  if (stagedResult.exitCode === 0) {
+    const planningFiles = stagedResult.stdout.split('\n').filter(f => f.startsWith('.planning/') || f.startsWith('.planning\\'));
 
     if (planningFiles.length > 0) {
       error(
@@ -994,14 +1004,14 @@ function cmdCheckCommit(cwd, raw) {
         `\n\nTo unstage: git reset HEAD ${planningFiles.join(' ')}`
       );
     }
-  } catch {
-    // git diff --cached failed (no staged files or not a git repo) — allow
   }
+  // exitCode !== 0 → no staged files or not a git repo — allow
 
   output({ allowed: true, reason: 'no_planning_files_staged' }, raw, 'allowed');
 }
 
 module.exports = {
+  determinePhaseStatus,
   cmdGenerateSlug,
   cmdCurrentTimestamp,
   cmdListTodos,

package/sdd/bin/lib/config-schema.cjs

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Single source of truth for valid config key paths.
+ *
+ * Imported by:
+ *   - config.cjs (isValidConfigKey validator)
+ *   - tests/config-schema-docs-parity.test.cjs (CI drift guard)
+ *
+ * Adding a key here without documenting it in docs/CONFIGURATION.md will
+ * fail the parity test. Adding a key to docs/CONFIGURATION.md without
+ * adding it here will cause config-set to reject it at runtime.
+ */
+
+/** Exact-match config key paths accepted by config-set. */
+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.ai_integration_phase', 'workflow.ui_phase', 'workflow.ui_safety_gate',
+  'workflow.auto_advance', 'workflow.node_repair', 'workflow.node_repair_budget',
+  'workflow.tdd_mode',
+  'workflow.human_verify_mode',
+  'workflow.text_mode',
+  'workflow.research_before_questions',
+  'workflow.discuss_mode',
+  'workflow.skip_discuss',
+  'workflow.auto_prune_state',
+  'workflow.use_worktrees',
+  'workflow.worktree_skip_hooks',
+  'workflow.code_review',
+  'workflow.code_review_depth',
+  'workflow.code_review_command',
+  'workflow.pattern_mapper',
+  'workflow.plan_bounce',
+  'workflow.plan_bounce_script',
+  'workflow.plan_bounce_passes',
+  'workflow.plan_chunked',
+  'workflow.plan_review_convergence',
+  'workflow.post_planning_gaps',
+  'workflow.security_enforcement',
+  'workflow.security_asvs_level',
+  'workflow.security_block_on',
+  'workflow.drift_threshold',
+  'workflow.drift_action',
+  'code_quality.fallow.enabled',
+  'code_quality.fallow.scope',
+  'code_quality.fallow.profile',
+  'code_quality.fallow.mcp',
+  'ship.pr_body_sections',
+  'git.branching_strategy', 'git.base_branch', 'git.create_tag', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
+  'planning.commit_docs', 'planning.search_gitignored', 'planning.sub_repos',
+  'review.ollama_host', 'review.lm_studio_host', 'review.llama_cpp_host',
+  'review.default_reviewers',
+  'workflow.cross_ai_execution', 'workflow.cross_ai_command', 'workflow.cross_ai_timeout',
+  'workflow.subagent_timeout',
+  'executor.stall_detect_interval_minutes',
+  'executor.stall_threshold_minutes',
+  'workflow.inline_plan_threshold',
+  'hooks.context_warnings',
+  'hooks.workflow_guard',
+  'workflow.context_coverage_gate',
+  'statusline.show_last_command',
+  'statusline.context_position',
+  'workflow.ui_review',
+  'workflow.max_discuss_passes',
+  'features.thinking_partner',
+  'context',
+  'features.global_learnings',
+  'learnings.max_inject',
+  'project_code', 'phase_naming',
+  'manager.flags.discuss', 'manager.flags.plan', 'manager.flags.execute',
+  'response_language',
+  'context_window',
+  'intel.enabled',
+  'graphify.enabled',
+  'graphify.build_timeout',
+  'claude_md_path',
+  'claude_md_assembly.mode',
+  // #2517 — runtime-aware model profiles
+  'runtime',
+  // #3162 — documented top-level key: controls model ID resolution for non-Claude runtimes
+  'resolve_model_ids',
+]);
+
+/**
+ * Internal runtime-state keys — accepted by config-set (workflows write them) but not
+ * exposed as user-settable options.  Excluded from VALID_CONFIG_KEYS so they stay out of
+ * the public docs-parity check and the "Valid keys:" error message.
+ * See: #3162 (workflow._auto_chain_active written by plan/execute/discuss workflows)
+ */
+const RUNTIME_STATE_KEYS = new Set([
+  'workflow._auto_chain_active',
+]);
+
+/**
+ * Dynamic-pattern validators — keys matching these regexes are also accepted.
+ * Each entry has a `test` function and a human-readable `description`.
+ */
+const DYNAMIC_KEY_PATTERNS = [
+  { topLevel: 'agent_skills',          test: (k) => /^agent_skills\.[a-zA-Z0-9_-]+$/.test(k),                   description: 'agent_skills.<agent-type>' },
+  { topLevel: 'review',                test: (k) => /^review\.models\.[a-zA-Z0-9_-]+$/.test(k),                 description: 'review.models.<cli-name>' },
+  { topLevel: 'features',              test: (k) => /^features\.[a-zA-Z0-9_]+$/.test(k),                        description: 'features.<feature_name>' },
+  { topLevel: 'claude_md_assembly',    test: (k) => /^claude_md_assembly\.blocks\.[a-zA-Z0-9_]+$/.test(k),      description: 'claude_md_assembly.blocks.<section>' },
+  // #2517 — runtime-aware model profile overrides: model_profile_overrides.<runtime>.<tier>
+  // <runtime> is a free string (so users can map non-built-in runtimes); <tier> is enum-restricted.
+  { topLevel: 'model_profile_overrides', test: (k) => /^model_profile_overrides\.[a-zA-Z0-9_-]+\.(opus|sonnet|haiku)$/.test(k),
+    description: 'model_profile_overrides.<runtime>.<opus|sonnet|haiku>' },
+  // #3023 — per-phase-type model map: models.<phase_type> = <tier>
+  // Six named slots (planning/discuss/research/execution/verification/completion);
+  // unknown phase-types are rejected. Per-agent model_overrides still take
+  // precedence over phase-type at resolve time.
+  { topLevel: 'models', test: (k) => /^models\.(planning|discuss|research|execution|verification|completion)$/.test(k),
+    description: 'models.<planning|discuss|research|execution|verification|completion>' },
+  // #3024 — dynamic routing block. Three top-level scalar settings
+  // plus a tier_models sub-block keyed by light/standard/heavy.
+  { topLevel: 'dynamic_routing',
+    test: (k) => /^dynamic_routing\.(enabled|escalate_on_failure|max_escalations|tier_models\.(light|standard|heavy))$/.test(k),
+    description: 'dynamic_routing.<enabled|escalate_on_failure|max_escalations|tier_models.<light|standard|heavy>>' },
+  // #3227 — per-agent model overrides: model_overrides.<agent-id>
+  // Full model IDs (e.g. "openai/o3") and tier aliases (opus/sonnet/haiku/inherit)
+  // are both accepted. Value validation is handled by the resolver at read time.
+  { topLevel: 'model_overrides', test: (k) => /^model_overrides\.[a-zA-Z0-9_-]+$/.test(k), description: 'model_overrides.<agent-id>' },
+];
+
+/**
+ * Returns true if keyPath is a valid config key (exact, dynamic pattern, or runtime state).
+ */
+function isValidConfigKey(keyPath) {
+  if (VALID_CONFIG_KEYS.has(keyPath)) return true;
+  if (RUNTIME_STATE_KEYS.has(keyPath)) return true;
+  return DYNAMIC_KEY_PATTERNS.some((p) => p.test(keyPath));
+}
+
+module.exports = { VALID_CONFIG_KEYS, RUNTIME_STATE_KEYS, DYNAMIC_KEY_PATTERNS, isValidConfigKey };