roadmapsmith 0.9.33 → 0.9.34

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"

package/README.md

@@ -8,7 +8,7 @@ This package owns the RoadmapSmith CLI, validator, sync engine, host setup files
 
 - `roadmapsmith setup`
 - `roadmapsmith zero`
-- `roadmapsmith maintain`
+- `roadmapsmith maintain [--dry-run]`
 - `roadmapsmith status [--json]`
 - `roadmapsmith validate [--json] [--strict]`
 - `roadmapsmith update [--task <stable-id> --evidence "<single-line evidence>"]`
@@ -40,11 +40,39 @@ This package owns the RoadmapSmith CLI, validator, sync engine, host setup files
 
 ### Zero Mode
 
-Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview, updates config, and generates the first roadmap.
+Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview when TTY is available, or consumes a complete brief from config plus flags in non-interactive environments.
+
+Non-interactive inputs:
+
+- `--product-name`
+- `--primary-user`
+- `--problem-statement`
+- `--target-outcome`
+- `--anti-goal` (repeatable)
+- `--preferred-stack`
+- `--constraint` (repeatable)
+- `--done-criterion` (repeatable)
+
+Without TTY, Zero Mode requires a complete brief from config/flags and fails clearly when required fields are missing.
 
 ### Sync/Audit Mode
 
-Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow.
+Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow for an existing managed roadmap block.
+
+If `ROADMAP.md` is authored and non-empty but has no `<!-- rs:managed:* -->` block:
+
+- `maintain` refuses to seed managed content implicitly
+- `update` is the conservative inline-annotation path
+- `generate` is the explicit managed-section creation path
+
+For write-capable surfaces (`maintain`, `generate`, `sync`, `update`), prefer `--dry-run` first.
+
+## Managed Block Ownership
+
+- `maintain` owns the managed roadmap block only.
+- `update` can annotate existing task lines even when no managed block exists.
+- `generate` is the explicit path that creates or replaces managed roadmap content.
+- Manually inserting empty `<!-- rs:managed:start -->` markers is no longer required as a workaround.
 
 ## Verification Model
 

package/bin/cli.js

@@ -14,14 +14,21 @@ const { generateRoadmapDocument } = require('../src/generator');
 const { parseRoadmap, tasksInManagedBlock } = require('../src/parser');
 const { buildValidationContext, validateTasks, auditValidation, CONFIDENCE_RANK, applyMinimumConfidence } = require('../src/validator');
 const { applySync } = require('../src/sync');
-const { buildZeroModeConfigPatch, buildZeroModeDefaults, collectZeroModeAnswers, isInteractiveTerminal } = require('../src/zero');
+const {
+  buildZeroModeConfigPatch,
+  collectZeroModeAnswers,
+  formatMissingZeroModeFields,
+  getMissingZeroModeFields,
+  isInteractiveTerminal,
+  resolveZeroModeAnswers
+} = require('../src/zero');
 
 function printHelp() {
   console.log([
     'Usage:',
     '  Canonical commands:',
-    '  roadmapsmith zero [--project-root <path>] [--config <path>]',
-    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen] [--refresh-annotations]',
+    '  roadmapsmith zero [--project-root <path>] [--config <path>] [--product-name <text>] [--primary-user <text>] [--problem-statement <text>] [--target-outcome <text>] [--anti-goal <text> ...] [--preferred-stack <text>] [--constraint <text> ...] [--done-criterion <text> ...]',
+    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--full-regen] [--refresh-annotations]',
     '  roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]',
     '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json] [--strict]',
     '  roadmapsmith update [--task <stable-id> --evidence <text>] [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]',
@@ -140,6 +147,42 @@ function formatSetupVerb(result, dryRun) {
   return result.before == null ? 'Created' : 'Updated';
 }
 
+function emitPreWriteWarning(roadmapFile, options = {}) {
+  if (options.dryRun || options.suppressWarning) {
+    return;
+  }
+  if (options.warningState && options.warningState.emitted) {
+    return;
+  }
+
+  const commandName = options.commandName || 'roadmapsmith';
+  console.log(`Warning: ${commandName} will modify ${roadmapFile}. Review the preview first with --dry-run.`);
+  if (options.managedSectionNote) {
+    console.log(options.managedSectionNote);
+  }
+
+  if (options.warningState) {
+    options.warningState.emitted = true;
+  }
+}
+
+function assertMaintainCanWrite(roadmapFile, content) {
+  if (content == null || String(content).trim().length === 0) {
+    return;
+  }
+
+  const parsed = parseRoadmap(content);
+  if (parsed.hasManagedBlock) {
+    return;
+  }
+
+  throw new Error(
+    `Refusing to let roadmapsmith maintain seed a managed section into an authored roadmap without <!-- rs:managed:start --> markers: ${roadmapFile}\n` +
+    'For conservative inline annotations, run `roadmapsmith update --dry-run` then `roadmapsmith update`.\n' +
+    'To intentionally create a managed section, run `roadmapsmith generate --dry-run` then `roadmapsmith generate`.'
+  );
+}
+
 function runInitCommand(projectRoot, config, flags) {
   const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
   const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
@@ -187,6 +230,13 @@ function runGenerateCommand(projectRoot, config, flags, options = {}) {
     forceFullRegenerate: options.forceFullRegenerate === true || isEnabled(flags['full-regen'])
   });
 
+  emitPreWriteWarning(roadmapFile, {
+    commandName: options.commandName || 'roadmapsmith generate',
+    dryRun,
+    suppressWarning: options.suppressPreWriteWarning,
+    warningState: options.warningState,
+    managedSectionNote: 'This command may create or replace a managed roadmap section depending on the current file state and flags.'
+  });
   const writeResult = writeText(roadmapFile, document, { dryRun });
   if (dryRun) {
     if (writeResult.changed) {
@@ -229,6 +279,12 @@ function runSyncCommand(projectRoot, config, flags, options = {}) {
   const forceRefresh = isEnabled(flags['refresh-annotations']);
   const next = applySync(content, syncTasks, results, { forceRefresh });
   const dryRun = isEnabled(flags['dry-run']);
+  emitPreWriteWarning(roadmapFile, {
+    commandName: options.commandName || 'roadmapsmith sync',
+    dryRun,
+    suppressWarning: options.suppressPreWriteWarning,
+    warningState: options.warningState
+  });
   const writeResult = writeText(roadmapFile, next, { dryRun });
 
   if (dryRun) {
@@ -266,7 +322,7 @@ function runUpdateCommand(projectRoot, config, flags) {
   const hasTask = flags.task != null;
   const hasEvidence = flags.evidence != null;
   if (!hasTask && !hasEvidence) {
-    runSyncCommand(projectRoot, config, flags);
+    runSyncCommand(projectRoot, config, flags, { commandName: 'roadmapsmith update' });
     return;
   }
   if (!hasTask || !hasEvidence || Array.isArray(flags.task) || Array.isArray(flags.evidence)) {
@@ -306,6 +362,10 @@ function runUpdateCommand(projectRoot, config, flags) {
 
   const next = applySync(draft, [draftTask], { [taskId]: result });
   const dryRun = isEnabled(flags['dry-run']);
+  emitPreWriteWarning(roadmapFile, {
+    commandName: 'roadmapsmith update',
+    dryRun
+  });
   const writeResult = writeText(roadmapFile, next, { dryRun });
   if (dryRun) {
     if (writeResult.changed) {
@@ -371,40 +431,69 @@ function runStatusCommand(projectRoot, config, flags, options = {}) {
 async function runZeroCommand(projectRoot, flags) {
   const configPath = resolveConfigPath({ projectRoot, configPath: flags.config });
   const config = loadConfig({ projectRoot, configPath: flags.config });
-  if (!isInteractiveTerminal(process.stdin, process.stdout)) {
-    throw new Error('Zero Mode requires an interactive terminal. Run roadmapsmith zero from a terminal session, or add a config/brief workflow before retrying in non-interactive mode.');
+  const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+  const roadmapExistedBeforeInit = fs.existsSync(roadmapFile);
+  const defaults = resolveZeroModeAnswers(projectRoot, config, flags);
+  const interactive = isInteractiveTerminal(process.stdin, process.stdout);
+  let answers = defaults;
+
+  if (!interactive) {
+    const missingFields = getMissingZeroModeFields(defaults);
+    if (missingFields.length > 0) {
+      throw new Error(
+        'Zero Mode requires a complete brief in non-interactive environments. Missing: ' +
+        `${formatMissingZeroModeFields(missingFields).join(', ')}. ` +
+        'Provide the missing values with CLI flags or in roadmap-skill.config.json before retrying.'
+      );
+    }
+    console.log('RoadmapSmith Zero Mode');
+    console.log('Using config/flag discovery inputs in non-interactive mode.\n');
+  } else {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    try {
+      console.log('RoadmapSmith Zero Mode');
+      console.log('Answer the discovery interview to generate the first roadmap.\n');
+      answers = await collectZeroModeAnswers((prompt) => rl.question(prompt), defaults);
+    } finally {
+      rl.close();
+    }
   }
 
-  const defaults = buildZeroModeDefaults(projectRoot, config);
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
+  const existingUserConfig = readUserConfig({ projectRoot, configPath: flags.config });
+  const nextUserConfig = buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers);
+  writeText(configPath, JSON.stringify(nextUserConfig, null, 2));
+  console.log(`Updated ${configPath}`);
+  const nextConfig = loadConfig({ projectRoot, configPath: flags.config });
+  runInitCommand(projectRoot, nextConfig, flags);
+  runGenerateCommand(projectRoot, nextConfig, flags, {
+    commandName: 'roadmapsmith zero',
+    suppressPreWriteWarning: true,
+    forceFullRegenerate: !roadmapExistedBeforeInit
   });
-
-  try {
-    console.log('RoadmapSmith Zero Mode');
-    console.log('Answer the discovery interview to generate the first roadmap.\n');
-    const answers = await collectZeroModeAnswers((prompt) => rl.question(prompt), defaults);
-    const existingUserConfig = readUserConfig({ projectRoot, configPath: flags.config });
-    const nextUserConfig = buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers);
-    writeText(configPath, JSON.stringify(nextUserConfig, null, 2));
-    console.log(`Updated ${configPath}`);
-    const nextConfig = loadConfig({ projectRoot, configPath: flags.config });
-    runInitCommand(projectRoot, nextConfig, flags);
-    runGenerateCommand(projectRoot, nextConfig, flags);
-  } finally {
-    rl.close();
-  }
 }
 
 function runMaintainCommand(projectRoot, flags) {
   const config = loadConfig({ projectRoot, configPath: flags.config });
+  const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+  const existingContent = readTextIfExists(roadmapFile);
+  assertMaintainCanWrite(roadmapFile, existingContent);
   const fullRegen = isEnabled(flags['full-regen']);
+  const warningState = { emitted: false };
   runGenerateCommand(projectRoot, config, flags, {
+    commandName: 'roadmapsmith maintain',
     preserveManagedBlock: !fullRegen,
-    forceFullRegenerate: fullRegen
+    forceFullRegenerate: fullRegen,
+    warningState
+  });
+  runSyncCommand(projectRoot, config, { ...flags, audit: true }, {
+    audit: true,
+    commandName: 'roadmapsmith maintain',
+    warningState
   });
-  runSyncCommand(projectRoot, config, { ...flags, audit: true }, { audit: true });
 }
 
 async function run() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "main": "src/index.js",
   "bin": {

package/skills/roadmap-maintain/SKILL.md

@@ -9,7 +9,8 @@ Use this command when the repository already has code, tests, docs, or an existi
 
 ## Required behavior
 
-1. Run `roadmapsmith maintain --project-root .`.
+1. Run `roadmapsmith maintain --project-root .`. Prefer `--dry-run` first when previewing impact.
 2. Treat this command as CLI-backed. Do not silently replace it with manual reasoning when the CLI is unavailable.
-3. Mention that maintain runs preserve-first generate, sync, and audit in one invocation.
-4. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.
+3. Mention that maintain runs preserve-first generate, sync, and audit in one invocation, but only for an existing managed roadmap block.
+4. If the roadmap is non-empty and lacks `<!-- rs:managed:* -->`, direct the user to `roadmapsmith update` for conservative inline annotations or `roadmapsmith generate` for explicit managed-section creation.
+5. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.

package/skills/roadmap-sync/agents/openai.yaml

@@ -2,6 +2,6 @@
   "interface": {
     "display_name": "Roadmap Sync (Deprecated)",
     "short_description": "DEPRECATED legacy root; use /roadmap-maintain or /roadmap-update.",
-    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update."
+    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update; use /roadmap-update when markers are missing."
   }
 }

package/skills/roadmap-zero/SKILL.md

@@ -10,4 +10,5 @@ Use this command when the repository is empty or low-context and the user needs
 ## Required behavior
 
 1. Run `roadmapsmith zero --project-root .`.
-2. If the CLI is missing, explain the install path instead of improvising the workflow manually.
+2. In non-interactive environments, provide or reuse a complete brief from config plus flags such as `--primary-user`, `--problem-statement`, `--target-outcome`, and repeatable `--done-criterion`.
+3. If the CLI is missing, explain the install path instead of improvising the workflow manually.

package/skills.json

@@ -12,7 +12,7 @@
     "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "roadmapsmith setup",
     "roadmapsmith zero",
-    "roadmapsmith maintain",
+    "roadmapsmith maintain --dry-run",
     "roadmapsmith /roadmap",
     "roadmapsmith update --task p2-customer-history --evidence \"src/app/api/customers/route.ts, test/customers.test.js\"",
     "roadmapsmith validate --json"
@@ -21,74 +21,74 @@
     "command": "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "source": "PapiScholz/roadmapsmith",
     "skill": "*",
-    "notes": "Recommended Claude Code install path for native GUI slash commands. Canonical surfaces: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-validate, /roadmap-update, /roadmap-setup. The public CLI update family covers both checklist refresh and verified single-task completion; sync remains the advanced alias for the mutating refresh path. Advanced surfaces: /roadmap-init, /roadmap-generate, /roadmap-audit. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the public readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
+    "notes": "Recommended Claude Code install path for native GUI slash commands. Canonical surfaces: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-validate, /roadmap-update, /roadmap-setup. The public CLI update family covers both checklist refresh and verified single-task completion; sync remains the advanced alias for the mutating refresh path. /roadmap-maintain now owns only existing managed roadmap blocks, while /roadmap-update is the conservative annotation path for authored roadmaps without markers. /roadmap-zero can consume a complete discovery brief from config plus CLI flags in non-interactive environments. Advanced surfaces: /roadmap-init, /roadmap-generate, /roadmap-audit. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the public readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
   },
   "skills": [
     {
       "name": "roadmap",
       "path": "skills/roadmap",
       "description": "Native slash palette for RoadmapSmith commands and recommended entrypoints across supported hosts.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
-      "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.33"
+      "description": "Native slash entrypoint for Zero Mode, including non-interactive config-plus-flag discovery.",
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
-      "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.33"
+      "description": "Native slash entrypoint for conservative managed-block maintenance plus sync and audit output.",
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-generate",
       "path": "skills/roadmap-generate",
       "description": "Native slash entrypoint for managed roadmap updates that require --full-regen before destructive replacement.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
-      "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
-      "version": "0.9.33"
+      "description": "Native slash entrypoint for evidence-backed inline annotation refresh and verified single-task completion.",
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
       "description": "Native slash entrypoint for the advanced sync-plus-audit mutating summary workflow.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.33"
+      "version": "0.9.34"
     }
   ]
 }

package/src/zero.js

@@ -2,6 +2,17 @@
 
 const path = require('path');
 
+const ZERO_MODE_FLAG_SPECS = {
+  productName: { flag: '--product-name', configPath: 'product.name', type: 'scalar' },
+  primaryUser: { flag: '--primary-user', configPath: 'product.primaryUser', type: 'scalar', required: true },
+  problemStatement: { flag: '--problem-statement', configPath: 'zeroMode.problemStatement', type: 'scalar', required: true },
+  targetOutcome: { flag: '--target-outcome', configPath: 'product.targetOutcome', type: 'scalar', required: true },
+  antiGoals: { flag: '--anti-goal', configPath: 'product.antiGoals', type: 'list' },
+  preferredStack: { flag: '--preferred-stack', configPath: 'zeroMode.preferredStack', type: 'scalar' },
+  constraints: { flag: '--constraint', configPath: 'zeroMode.constraints', type: 'list' },
+  doneCriteria: { flag: '--done-criterion', configPath: 'zeroMode.doneCriteria', type: 'list', required: true }
+};
+
 const ZERO_MODE_QUESTIONS = [
   { id: 'productName', prompt: '1. What product are we building?' },
   { id: 'primaryUser', prompt: '2. Who is the target user?' },
@@ -54,6 +65,80 @@ function buildZeroModeDefaults(projectRoot, config) {
   };
 }
 
+function getSingleFlagValue(value) {
+  if (Array.isArray(value)) {
+    return value[value.length - 1];
+  }
+  return value;
+}
+
+function getListFlagValues(value) {
+  const rawValues = Array.isArray(value) ? value : [value];
+  return rawValues.flatMap((item) => splitListAnswer(item));
+}
+
+function resolveZeroModeAnswers(projectRoot, config, flags = {}) {
+  const defaults = buildZeroModeDefaults(projectRoot, config);
+  const answers = { ...defaults };
+
+  for (const [field, spec] of Object.entries(ZERO_MODE_FLAG_SPECS)) {
+    const flagKey = spec.flag.slice(2);
+    if (!Object.prototype.hasOwnProperty.call(flags, flagKey)) {
+      continue;
+    }
+
+    if (spec.type === 'list') {
+      answers[field] = getListFlagValues(flags[flagKey]).join('; ');
+      continue;
+    }
+
+    const raw = getSingleFlagValue(flags[flagKey]);
+    answers[field] = String(raw == null ? '' : raw).trim();
+  }
+
+  if (!String(answers.productName || '').trim()) {
+    answers.productName = path.basename(projectRoot);
+  }
+
+  return answers;
+}
+
+function getMissingZeroModeFields(answers = {}) {
+  const missing = [];
+  for (const [field, spec] of Object.entries(ZERO_MODE_FLAG_SPECS)) {
+    if (!spec.required) {
+      continue;
+    }
+
+    if (spec.type === 'list') {
+      if (splitListAnswer(answers[field]).length === 0) {
+        missing.push({
+          field,
+          flag: spec.flag,
+          configPath: spec.configPath
+        });
+      }
+      continue;
+    }
+
+    if (!String(answers[field] || '').trim()) {
+      missing.push({
+        field,
+        flag: spec.flag,
+        configPath: spec.configPath
+      });
+    }
+  }
+  return missing;
+}
+
+function formatMissingZeroModeFields(missingFields) {
+  return missingFields.map((item) => {
+    const label = item.field.replace(/([A-Z])/g, ' $1').toLowerCase();
+    return `${label} (${item.flag} or config ${item.configPath})`;
+  });
+}
+
 async function collectZeroModeAnswers(ask, defaults = {}) {
   const answers = {};
   for (const question of ZERO_MODE_QUESTIONS) {
@@ -124,6 +209,9 @@ module.exports = {
   buildZeroModeConfigPatch,
   buildZeroModeDefaults,
   collectZeroModeAnswers,
+  formatMissingZeroModeFields,
+  getMissingZeroModeFields,
   isInteractiveTerminal,
+  resolveZeroModeAnswers,
   splitListAnswer
 };