@ryuenn3123/agentic-senior-core 2.5.21 → 3.0.0

package/lib/cli/init-architecture-flow.mjs

@@ -0,0 +1,231 @@
+import path from 'node:path';
+
+import {
+  PROJECT_SCOPE_CHOICES,
+  BLUEPRINT_RECOMMENDATIONS,
+} from './constants.mjs';
+
+import {
+  recommendArchitecture,
+  formatArchitectureRecommendation,
+  createUpdatedArchitectPreference,
+  shouldApplyRepeatedOverridePreference,
+} from './architect.mjs';
+
+import {
+  askChoice,
+  askYesNo,
+  toTitleCase,
+} from './utils.mjs';
+
+import {
+  filterStackFileNamesByCandidates,
+  filterBlueprintFileNamesByCandidates,
+  resolveProjectScopeKeyFromLabel,
+  resolveScopeStackCandidates,
+  resolveScopeBlueprintCandidates,
+} from './init-selection.mjs';
+
+const DEFAULT_PROJECT_SCOPE_KEY = 'both';
+const DEFAULT_PROJECT_SCOPE_LABEL = PROJECT_SCOPE_CHOICES.find(
+  (scopeChoice) => scopeChoice.key === DEFAULT_PROJECT_SCOPE_KEY
+)?.label || 'Both (frontend + backend)';
+
+export async function resolveArchitectureSelection({
+  shouldRunArchitectureRecommendation,
+  initOptions,
+  projectDetection,
+  stackFileNames,
+  blueprintFileNames,
+  userInterface,
+  isInteractiveSession,
+  initialSelectedProjectScopeKey,
+  initialSelectedProjectScopeLabel,
+  initialSelectedManualStackFileName,
+  initialSelectedManualBlueprintFileName,
+  architectPreferenceState,
+  askStackSelection,
+  askBlueprintSelection,
+  detectionTransparency,
+}) {
+  let selectedProjectScopeKey = initialSelectedProjectScopeKey || DEFAULT_PROJECT_SCOPE_KEY;
+  let selectedProjectScopeLabel = initialSelectedProjectScopeLabel || DEFAULT_PROJECT_SCOPE_LABEL;
+  let selectedManualStackFileName = initialSelectedManualStackFileName || null;
+  let selectedManualBlueprintFileName = initialSelectedManualBlueprintFileName || null;
+  let architectureRecommendation = null;
+  let nextArchitectPreferenceState = architectPreferenceState;
+  let architectPreferenceUpdated = false;
+
+  if (!shouldRunArchitectureRecommendation) {
+    return {
+      selectedProjectScopeKey,
+      selectedProjectScopeLabel,
+      selectedManualStackFileName,
+      selectedManualBlueprintFileName,
+      architectureRecommendation,
+      architectPreferenceState: nextArchitectPreferenceState,
+      architectPreferenceUpdated,
+    };
+  }
+
+  let architectureProjectDescription = String(initOptions.projectDescription || '').trim();
+  const isFreshProjectFlow = !projectDetection.hasExistingProjectFiles;
+
+  if (isFreshProjectFlow && isInteractiveSession) {
+    const selectedProjectScopeInput = await askChoice(
+      'Project domain (frontend only, backend only, or both):',
+      PROJECT_SCOPE_CHOICES.map((scopeChoice) => scopeChoice.label),
+      userInterface
+    );
+
+    selectedProjectScopeKey = resolveProjectScopeKeyFromLabel(selectedProjectScopeInput);
+    selectedProjectScopeLabel = selectedProjectScopeInput;
+
+    if (!architectureProjectDescription) {
+      architectureProjectDescription = (await userInterface.question(
+        '\nProject description (free text): '
+      )).trim();
+    }
+  }
+
+  if (!architectureProjectDescription && isInteractiveSession && !isFreshProjectFlow) {
+    architectureProjectDescription = (await userInterface.question(
+      '\nDescribe your project in one short paragraph for architecture recommendation: '
+    )).trim();
+  }
+
+  if (!architectureProjectDescription) {
+    architectureProjectDescription = `A software project named ${path.basename(initOptions.targetDirectoryPath)}.`;
+  }
+
+  const scopeStackCandidates = filterStackFileNamesByCandidates(
+    stackFileNames,
+    resolveScopeStackCandidates(selectedProjectScopeKey)
+  );
+  const scopeBlueprintCandidates = filterBlueprintFileNamesByCandidates(
+    blueprintFileNames,
+    resolveScopeBlueprintCandidates(selectedProjectScopeKey)
+  );
+
+  architectureRecommendation = recommendArchitecture({
+    projectDescription: architectureProjectDescription,
+    projectDetection,
+    stackFileNames: scopeStackCandidates,
+    blueprintFileNames: scopeBlueprintCandidates,
+    tokenBudget: initOptions.architectTokenBudget,
+    timeoutMs: initOptions.architectTimeoutMs,
+    researchMode: initOptions.architectResearchMode,
+    enableRealtimeResearch: initOptions.enableRealtimeResearch,
+    realtimeSignalFilePath: initOptions.architectRealtimeSignalFile,
+  });
+
+  architectureRecommendation.projectDomain = {
+    key: selectedProjectScopeKey,
+    label: selectedProjectScopeLabel,
+  };
+
+  architectureRecommendation.userVeto = {
+    applied: false,
+    selectedStackFileName: architectureRecommendation.recommendedStackFileName,
+    selectedBlueprintFileName: architectureRecommendation.recommendedBlueprintFileName,
+    source: 'recommendation',
+  };
+
+  console.log(formatArchitectureRecommendation(architectureRecommendation));
+
+  const shouldSkipRecommendationDebate = shouldApplyRepeatedOverridePreference(
+    nextArchitectPreferenceState,
+    architectureRecommendation.recommendedStackFileName
+  );
+
+  if (isFreshProjectFlow) {
+    selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
+    selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
+
+    if (detectionTransparency) {
+      detectionTransparency.quickConfirmation.response = 'fresh-project-two-question';
+      detectionTransparency.decision.mode = 'fresh-project-two-question-auto';
+    }
+  } else if (shouldSkipRecommendationDebate) {
+    architectureRecommendation.failureModes.repeatedOverride = true;
+    selectedManualStackFileName = stackFileNames.includes(nextArchitectPreferenceState.preferredStackFileName)
+      ? nextArchitectPreferenceState.preferredStackFileName
+      : architectureRecommendation.recommendedStackFileName;
+    selectedManualBlueprintFileName = blueprintFileNames.includes(nextArchitectPreferenceState.preferredBlueprintFileName)
+      ? nextArchitectPreferenceState.preferredBlueprintFileName
+      : architectureRecommendation.recommendedBlueprintFileName;
+    architectureRecommendation.userVeto = {
+      applied: true,
+      selectedStackFileName: selectedManualStackFileName,
+      selectedBlueprintFileName: selectedManualBlueprintFileName,
+      source: 'saved-preference',
+    };
+    console.log(
+      `Repeated override preference detected. Applying ${toTitleCase(selectedManualStackFileName)} + ${toTitleCase(selectedManualBlueprintFileName)} without additional debate.`
+    );
+  } else if (!isInteractiveSession) {
+    selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
+    selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
+  } else {
+    const shouldApplyRecommendedArchitecture = await askYesNo(
+      'Apply this architecture recommendation?',
+      userInterface,
+      true
+    );
+
+    if (shouldApplyRecommendedArchitecture) {
+      selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
+      selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
+    } else {
+      const vetoStackFileName = await askStackSelection(
+        'User veto received. Select stack to apply immediately:',
+        stackFileNames,
+        userInterface
+      );
+
+      const vetoBlueprintCandidates = filterBlueprintFileNamesByCandidates(
+        blueprintFileNames,
+        [BLUEPRINT_RECOMMENDATIONS[vetoStackFileName]].filter(Boolean)
+      );
+
+      const vetoBlueprintFileName = await askBlueprintSelection(
+        'Select blueprint to apply immediately (no further debate):',
+        vetoBlueprintCandidates,
+        userInterface
+      );
+
+      selectedManualStackFileName = vetoStackFileName;
+      selectedManualBlueprintFileName = vetoBlueprintFileName;
+      architectureRecommendation.userVeto = {
+        applied: true,
+        selectedStackFileName: vetoStackFileName,
+        selectedBlueprintFileName: vetoBlueprintFileName,
+        source: 'interactive-veto',
+      };
+
+      nextArchitectPreferenceState = createUpdatedArchitectPreference(nextArchitectPreferenceState, {
+        selectedStackFileName: vetoStackFileName,
+        selectedBlueprintFileName: vetoBlueprintFileName,
+      });
+      architectPreferenceUpdated = true;
+
+      if (nextArchitectPreferenceState.overrideCount >= 2) {
+        architectureRecommendation.failureModes.repeatedOverride = true;
+      }
+
+      console.log(
+        `Veto applied. Proceeding with ${toTitleCase(vetoStackFileName)} + ${toTitleCase(vetoBlueprintFileName)} without recommendation loops.`
+      );
+    }
+  }
+
+  return {
+    selectedProjectScopeKey,
+    selectedProjectScopeLabel,
+    selectedManualStackFileName,
+    selectedManualBlueprintFileName,
+    architectureRecommendation,
+    architectPreferenceState: nextArchitectPreferenceState,
+    architectPreferenceUpdated,
+  };
+}

package/lib/cli/init-detection-flow.mjs

@@ -0,0 +1,123 @@
+import {
+  BLUEPRINT_RECOMMENDATIONS,
+} from './constants.mjs';
+
+import {
+  filterBlueprintFileNamesByCandidates,
+  normalizeAdditionalStackSelection,
+} from './init-selection.mjs';
+
+import {
+  toTitleCase,
+} from './utils.mjs';
+
+export function buildExistingProjectMajorConstraints() {
+  return [
+    'Preserve existing project markers and avoid forced stack migration.',
+    'Keep stack rule loading lazy and scoped to touched code.',
+    'Explicit stack or blueprint overrides always win over auto-detection.',
+  ];
+}
+
+export async function resolveDetectedSetupDecision({
+  shouldAutoApplyDetectedStack,
+  projectDetection,
+  stackFileNames,
+  blueprintFileNames,
+  userInterface,
+  isInteractiveSession,
+  detectionTransparency,
+  askYesNo,
+  askStackSelection,
+  askBlueprintSelection,
+  initialSelectedManualStackFileName,
+  initialSelectedManualBlueprintFileName,
+  initialSelectedAdditionalStackFileNames,
+}) {
+  let selectedManualStackFileName = initialSelectedManualStackFileName || null;
+  let selectedManualBlueprintFileName = initialSelectedManualBlueprintFileName || null;
+  let selectedAdditionalStackFileNames = initialSelectedAdditionalStackFileNames || [];
+  let detectedSetupWasApplied = false;
+
+  const detectedBlueprintFileName = projectDetection.recommendedBlueprintFileName
+    || BLUEPRINT_RECOMMENDATIONS[projectDetection.recommendedStackFileName]
+    || null;
+
+  if (shouldAutoApplyDetectedStack) {
+    if (isInteractiveSession) {
+      detectionTransparency.quickConfirmation.offered = true;
+      console.log('\nQuick confirmation for existing project detection:');
+      console.log(`- Suggested stack: ${toTitleCase(projectDetection.recommendedStackFileName)}`);
+      if (detectedBlueprintFileName) {
+        console.log(`- Suggested blueprint: ${toTitleCase(detectedBlueprintFileName)}`);
+      }
+
+      const shouldUseDetectedSetup = await askYesNo(
+        'Use detected setup for this existing project?',
+        userInterface,
+        true
+      );
+
+      if (shouldUseDetectedSetup) {
+        detectedSetupWasApplied = true;
+        detectionTransparency.quickConfirmation.response = 'confirmed-detected';
+        detectionTransparency.decision.mode = 'confirmed-detected';
+        console.log(`Using detected stack automatically for this existing project: ${toTitleCase(projectDetection.recommendedStackFileName)}.`);
+        if (projectDetection.secondaryStackFileNames?.length) {
+          console.log(`Detected additional stack signals: ${projectDetection.secondaryStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}.`);
+        }
+        selectedAdditionalStackFileNames = projectDetection.secondaryStackFileNames || [];
+      } else {
+        const overrideStackFileName = await askStackSelection(
+          'Override detected stack (quick selection):',
+          stackFileNames,
+          userInterface
+        );
+        const overrideBlueprintCandidates = filterBlueprintFileNamesByCandidates(
+          blueprintFileNames,
+          [BLUEPRINT_RECOMMENDATIONS[overrideStackFileName]].filter(Boolean)
+        );
+        const overrideBlueprintFileName = await askBlueprintSelection(
+          'Override detected blueprint (quick selection):',
+          overrideBlueprintCandidates,
+          userInterface
+        );
+
+        selectedManualStackFileName = overrideStackFileName;
+        selectedManualBlueprintFileName = overrideBlueprintFileName;
+        selectedAdditionalStackFileNames = normalizeAdditionalStackSelection(
+          overrideStackFileName,
+          projectDetection.secondaryStackFileNames || []
+        );
+        detectionTransparency.quickConfirmation.response = 'overridden-detected';
+        detectionTransparency.decision.mode = 'overridden-detected';
+        console.log(
+          `Detection override applied: ${toTitleCase(overrideStackFileName)} + ${toTitleCase(overrideBlueprintFileName)}.`
+        );
+      }
+    } else {
+      detectedSetupWasApplied = true;
+      detectionTransparency.quickConfirmation.response = 'non-interactive-auto';
+      detectionTransparency.decision.mode = 'non-interactive-auto';
+      console.log(`Using detected stack automatically for this existing project: ${toTitleCase(projectDetection.recommendedStackFileName)}.`);
+      if (projectDetection.secondaryStackFileNames?.length) {
+        console.log(`Detected additional stack signals: ${projectDetection.secondaryStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}.`);
+      }
+      selectedAdditionalStackFileNames = projectDetection.secondaryStackFileNames || [];
+    }
+  } else if (projectDetection.hasExistingProjectFiles && projectDetection.recommendedStackFileName) {
+    detectionTransparency.quickConfirmation.response = 'explicit-selection-or-low-confidence';
+    detectionTransparency.decision.mode = 'explicit-selection-or-low-confidence';
+  } else if (!projectDetection.hasExistingProjectFiles) {
+    detectionTransparency.quickConfirmation.response = 'not-applicable';
+    detectionTransparency.decision.mode = 'fresh-directory';
+  }
+
+  return {
+    detectedSetupWasApplied,
+    selectedManualStackFileName,
+    selectedManualBlueprintFileName,
+    selectedAdditionalStackFileNames,
+    detectedBlueprintFileName,
+  };
+}

package/lib/cli/init-options.mjs

@@ -0,0 +1,344 @@
+/**
+ * Init Options Parser — isolates CLI option parsing from init runtime flow.
+ */
+import {
+  ARCHITECT_DEFAULT_TOKEN_BUDGET,
+  ARCHITECT_DEFAULT_TIMEOUT_MS,
+  ARCHITECT_MIN_TOKEN_BUDGET,
+  ARCHITECT_MAX_TOKEN_BUDGET,
+  ARCHITECT_MIN_TIMEOUT_MS,
+  ARCHITECT_MAX_TIMEOUT_MS,
+} from './architect.mjs';
+import { normalizeDocsLanguage } from './project-scaffolder.mjs';
+import { normalizeAgentName } from './token-optimization.mjs';
+import { normalizeChoiceInput, matchProfileNameFromInput } from './utils.mjs';
+
+const INIT_DEFAULT_RESEARCH_MODE = 'realtime';
+
+export function normalizeRuntimeEnvironmentKey(rawRuntimeEnvironmentKey) {
+  const normalizedRuntimeEnvironmentKey = normalizeChoiceInput(String(rawRuntimeEnvironmentKey || 'auto'));
+  const supportedRuntimeEnvironmentKeys = new Set(['auto', 'linux-wsl', 'linux', 'windows', 'macos']);
+  return supportedRuntimeEnvironmentKeys.has(normalizedRuntimeEnvironmentKey) ? normalizedRuntimeEnvironmentKey : null;
+}
+
+export function parseInitArguments(commandArguments) {
+  const parsedInitOptions = {
+    targetDirectory: '.',
+    preset: undefined,
+    profile: undefined,
+    profilePack: undefined,
+    stack: undefined,
+    blueprint: undefined,
+    ci: undefined,
+    newbie: false,
+    tokenOptimize: true,
+    memoryContinuity: true,
+    tokenAgent: 'copilot',
+    includeMcpTemplate: true,
+    scaffoldDocs: undefined,
+    docsLang: 'en',
+    docsLangProvided: false,
+    projectConfig: undefined,
+    projectDescription: '',
+    architectTokenBudget: ARCHITECT_DEFAULT_TOKEN_BUDGET,
+    architectTimeoutMs: ARCHITECT_DEFAULT_TIMEOUT_MS,
+    architectResearchMode: INIT_DEFAULT_RESEARCH_MODE,
+    enableRealtimeResearch: true,
+    architectRealtimeSignalFile: null,
+    runtimeEnv: 'auto',
+    runtimeEnvProvided: false,
+  };
+
+  for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
+    const currentArgument = commandArguments[argumentIndex];
+
+    if (!currentArgument.startsWith('--')) {
+      parsedInitOptions.targetDirectory = currentArgument;
+      continue;
+    }
+
+    if (currentArgument === '--profile') {
+      parsedInitOptions.profile = matchProfileNameFromInput(commandArguments[argumentIndex + 1] || '');
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument === '--preset') {
+      parsedInitOptions.preset = normalizeChoiceInput(commandArguments[argumentIndex + 1] || '');
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--preset=')) {
+      parsedInitOptions.preset = normalizeChoiceInput(currentArgument.split('=')[1]);
+      continue;
+    }
+
+    if (currentArgument.startsWith('--profile=')) {
+      parsedInitOptions.profile = matchProfileNameFromInput(currentArgument.split('=')[1]);
+      continue;
+    }
+
+    if (currentArgument === '--profile-pack') {
+      parsedInitOptions.profilePack = commandArguments[argumentIndex + 1];
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--profile-pack=')) {
+      parsedInitOptions.profilePack = currentArgument.split('=')[1];
+      continue;
+    }
+
+    if (currentArgument === '--stack') {
+      parsedInitOptions.stack = commandArguments[argumentIndex + 1];
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--stack=')) {
+      parsedInitOptions.stack = currentArgument.split('=')[1];
+      continue;
+    }
+
+    if (currentArgument === '--blueprint') {
+      parsedInitOptions.blueprint = commandArguments[argumentIndex + 1];
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--blueprint=')) {
+      parsedInitOptions.blueprint = currentArgument.split('=')[1];
+      continue;
+    }
+
+    if (currentArgument === '--ci') {
+      const ciRawValue = commandArguments[argumentIndex + 1];
+      parsedInitOptions.ci = ciRawValue?.toLowerCase() === 'true';
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--ci=')) {
+      parsedInitOptions.ci = currentArgument.split('=')[1]?.toLowerCase() === 'true';
+      continue;
+    }
+
+    if (currentArgument === '--newbie') {
+      parsedInitOptions.newbie = true;
+      continue;
+    }
+
+    if (currentArgument === '--token-optimize') {
+      parsedInitOptions.tokenOptimize = true;
+      continue;
+    }
+
+    if (currentArgument === '--memory-continuity') {
+      parsedInitOptions.memoryContinuity = true;
+      continue;
+    }
+
+    if (currentArgument === '--token-agent') {
+      parsedInitOptions.tokenAgent = commandArguments[argumentIndex + 1] || 'copilot';
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--token-agent=')) {
+      parsedInitOptions.tokenAgent = currentArgument.split('=')[1] || 'copilot';
+      continue;
+    }
+
+    if (currentArgument === '--no-token-optimize') {
+      parsedInitOptions.tokenOptimize = false;
+      continue;
+    }
+
+    if (currentArgument === '--no-memory-continuity') {
+      parsedInitOptions.memoryContinuity = false;
+      continue;
+    }
+
+    if (currentArgument === '--mcp-template') {
+      parsedInitOptions.includeMcpTemplate = true;
+      continue;
+    }
+
+    if (currentArgument === '--no-mcp-template') {
+      parsedInitOptions.includeMcpTemplate = false;
+      continue;
+    }
+
+    if (currentArgument === '--scaffold-docs') {
+      parsedInitOptions.scaffoldDocs = true;
+      continue;
+    }
+
+    if (currentArgument === '--no-scaffold-docs') {
+      parsedInitOptions.scaffoldDocs = false;
+      continue;
+    }
+
+    if (currentArgument === '--docs-lang') {
+      parsedInitOptions.docsLang = commandArguments[argumentIndex + 1] || 'en';
+      parsedInitOptions.docsLangProvided = true;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--docs-lang=')) {
+      parsedInitOptions.docsLang = currentArgument.split('=')[1] || 'en';
+      parsedInitOptions.docsLangProvided = true;
+      continue;
+    }
+
+    if (currentArgument === '--project-config') {
+      parsedInitOptions.projectConfig = commandArguments[argumentIndex + 1];
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--project-config=')) {
+      parsedInitOptions.projectConfig = currentArgument.split('=')[1];
+      continue;
+    }
+
+    if (currentArgument === '--project-description') {
+      parsedInitOptions.projectDescription = commandArguments[argumentIndex + 1] || '';
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--project-description=')) {
+      parsedInitOptions.projectDescription = currentArgument.split('=')[1] || '';
+      continue;
+    }
+
+    if (currentArgument === '--architect-token-budget') {
+      const rawTokenBudget = Number.parseInt(commandArguments[argumentIndex + 1], 10);
+      if (Number.isNaN(rawTokenBudget)) {
+        throw new Error('--architect-token-budget must be a number');
+      }
+      parsedInitOptions.architectTokenBudget = rawTokenBudget;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-token-budget=')) {
+      const rawTokenBudget = Number.parseInt(currentArgument.split('=')[1], 10);
+      if (Number.isNaN(rawTokenBudget)) {
+        throw new Error('--architect-token-budget must be a number');
+      }
+      parsedInitOptions.architectTokenBudget = rawTokenBudget;
+      continue;
+    }
+
+    if (currentArgument === '--architect-timeout-ms') {
+      const rawTimeoutMs = Number.parseInt(commandArguments[argumentIndex + 1], 10);
+      if (Number.isNaN(rawTimeoutMs)) {
+        throw new Error('--architect-timeout-ms must be a number');
+      }
+      parsedInitOptions.architectTimeoutMs = rawTimeoutMs;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-timeout-ms=')) {
+      const rawTimeoutMs = Number.parseInt(currentArgument.split('=')[1], 10);
+      if (Number.isNaN(rawTimeoutMs)) {
+        throw new Error('--architect-timeout-ms must be a number');
+      }
+      parsedInitOptions.architectTimeoutMs = rawTimeoutMs;
+      continue;
+    }
+
+    if (currentArgument === '--architect-research-mode') {
+      parsedInitOptions.architectResearchMode = commandArguments[argumentIndex + 1] || INIT_DEFAULT_RESEARCH_MODE;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-research-mode=')) {
+      parsedInitOptions.architectResearchMode = currentArgument.split('=')[1] || INIT_DEFAULT_RESEARCH_MODE;
+      continue;
+    }
+
+    if (currentArgument === '--enable-realtime-research') {
+      parsedInitOptions.enableRealtimeResearch = true;
+      continue;
+    }
+
+    if (currentArgument === '--disable-realtime-research') {
+      parsedInitOptions.enableRealtimeResearch = false;
+      continue;
+    }
+
+    if (currentArgument === '--architect-realtime-signal-file') {
+      parsedInitOptions.architectRealtimeSignalFile = commandArguments[argumentIndex + 1] || null;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-realtime-signal-file=')) {
+      parsedInitOptions.architectRealtimeSignalFile = currentArgument.split('=')[1] || null;
+      continue;
+    }
+
+    if (currentArgument === '--runtime-env') {
+      parsedInitOptions.runtimeEnv = commandArguments[argumentIndex + 1] || 'auto';
+      parsedInitOptions.runtimeEnvProvided = true;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--runtime-env=')) {
+      parsedInitOptions.runtimeEnv = currentArgument.split('=')[1] || 'auto';
+      parsedInitOptions.runtimeEnvProvided = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${currentArgument}`);
+  }
+
+  if (parsedInitOptions.newbie && parsedInitOptions.profile && parsedInitOptions.profile !== 'beginner') {
+    throw new Error('--newbie can only be combined with --profile beginner');
+  }
+
+  const normalizedDocsLanguage = normalizeDocsLanguage(parsedInitOptions.docsLang || 'en');
+  if (!normalizedDocsLanguage) {
+    throw new Error('--docs-lang must be one of: en, id');
+  }
+
+  const normalizedRuntimeEnvironment = normalizeRuntimeEnvironmentKey(parsedInitOptions.runtimeEnv || 'auto');
+  if (!normalizedRuntimeEnvironment) {
+    throw new Error('--runtime-env must be one of: auto, linux-wsl, linux, windows, macos');
+  }
+
+  if (!Number.isInteger(parsedInitOptions.architectTokenBudget)
+    || parsedInitOptions.architectTokenBudget < ARCHITECT_MIN_TOKEN_BUDGET
+    || parsedInitOptions.architectTokenBudget > ARCHITECT_MAX_TOKEN_BUDGET) {
+    throw new Error(`--architect-token-budget must be an integer between ${ARCHITECT_MIN_TOKEN_BUDGET} and ${ARCHITECT_MAX_TOKEN_BUDGET}`);
+  }
+
+  if (!Number.isInteger(parsedInitOptions.architectTimeoutMs)
+    || parsedInitOptions.architectTimeoutMs < ARCHITECT_MIN_TIMEOUT_MS
+    || parsedInitOptions.architectTimeoutMs > ARCHITECT_MAX_TIMEOUT_MS) {
+    throw new Error(`--architect-timeout-ms must be an integer between ${ARCHITECT_MIN_TIMEOUT_MS} and ${ARCHITECT_MAX_TIMEOUT_MS}`);
+  }
+
+  const normalizedArchitectResearchMode = normalizeChoiceInput(
+    parsedInitOptions.architectResearchMode || INIT_DEFAULT_RESEARCH_MODE
+  );
+  const supportedArchitectResearchModes = new Set(['snapshot', 'realtime']);
+  if (!supportedArchitectResearchModes.has(normalizedArchitectResearchMode)) {
+    throw new Error('--architect-research-mode must be one of: snapshot, realtime');
+  }
+
+  parsedInitOptions.docsLang = normalizedDocsLanguage;
+  parsedInitOptions.runtimeEnv = normalizedRuntimeEnvironment;
+  parsedInitOptions.tokenAgent = normalizeAgentName(parsedInitOptions.tokenAgent);
+  parsedInitOptions.architectResearchMode = normalizedArchitectResearchMode;
+
+  return parsedInitOptions;
+}