@ryuenn3123/agentic-senior-core 3.0.12 → 3.0.14

package/lib/cli/commands/init.mjs

@@ -8,13 +8,13 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import {
+  PROJECT_SCOPE_CHOICES,
   CLI_VERSION,
   AGENT_CONTEXT_DIR,
   INIT_PRESETS,
   PROFILE_PRESETS,
   GOLDEN_STANDARD_PROFILE_NAME,
   BLUEPRINT_RECOMMENDATIONS,
-  PROJECT_SCOPE_CHOICES,
   FALLBACK_STACK_FILE_NAMES,
   FALLBACK_BLUEPRINT_FILE_NAMES,
   RUNTIME_ENVIRONMENT_CHOICES,
@@ -42,10 +42,13 @@ import {
 } from '../detector.mjs';
 import { compileDynamicContext, writeSelectedPolicy, writeOnboardingReport } from '../compiler.mjs';
 import {
+  filterStackFileNamesByCandidates,
   filterBlueprintFileNamesByCandidates,
   normalizeAdditionalStackSelection,
   normalizeAdditionalBlueprintSelection,
   deriveAdditionalBlueprintFileNamesFromStacks,
+  resolveScopeStackCandidates,
+  resolveScopeBlueprintCandidates,
 } from '../init-selection.mjs';
 import {
   buildExistingProjectMajorConstraints,
@@ -75,11 +78,7 @@ import {
   createMemoryContinuityState,
   writeMemoryContinuityState,
 } from '../memory-continuity.mjs';
-import {
-  readArchitectPreferenceState,
-  writeArchitectPreferenceState,
-} from '../architect.mjs';
-import { resolveArchitectureSelection } from '../init-architecture-flow.mjs';
+import { recommendArchitecture } from '../architect.mjs';
 
 export { REPO_ROOT } from '../constants.mjs';
 // Keep these architect option flags visible in the init command surface for validator coverage:
@@ -156,6 +155,82 @@ export function detectRuntimeEnvironment() {
   };
 }
 
+function resolveProjectScopeLabelFromKey(projectScopeKey) {
+  return PROJECT_SCOPE_CHOICES.find((scopeChoice) => scopeChoice.key === projectScopeKey)?.label
+    || PROJECT_SCOPE_CHOICES.find((scopeChoice) => scopeChoice.key === 'both')?.label
+    || 'Both (frontend + backend)';
+}
+
+function inferProjectScopeFromDiscoveryAnswers(discoveryAnswers) {
+  const normalizedDomain = String(discoveryAnswers?.primaryDomain || '').trim().toLowerCase();
+  const normalizedDescription = [
+    discoveryAnswers?.projectDescription,
+    ...(Array.isArray(discoveryAnswers?.features) ? discoveryAnswers.features : []),
+  ].join(' ').toLowerCase();
+
+  if (
+    normalizedDomain.includes('api service')
+    || normalizedDomain.includes('cli tool')
+    || normalizedDomain.includes('library')
+  ) {
+    return 'backend-only';
+  }
+
+  if (normalizedDomain.includes('mobile app')) {
+    return 'frontend-only';
+  }
+
+  if (normalizedDomain.includes('web application')) {
+    if (/(landing page|marketing site|showcase|portfolio|brochure|company profile)/.test(normalizedDescription)) {
+      return 'frontend-only';
+    }
+
+    return 'both';
+  }
+
+  return 'both';
+}
+
+function resolveSilentCiGuardrailsDefault({
+  initOptions,
+  selectedPreset,
+  selectedProfilePack,
+  selectedProfile,
+}) {
+  if (typeof initOptions.ci === 'boolean') {
+    return {
+      value: initOptions.ci,
+      shouldAsk: false,
+    };
+  }
+
+  if (typeof selectedPreset?.ci === 'boolean') {
+    return {
+      value: selectedPreset.ci,
+      shouldAsk: false,
+    };
+  }
+
+  if (typeof selectedProfilePack?.defaultCi === 'boolean') {
+    return {
+      value: selectedProfilePack.defaultCi,
+      shouldAsk: Boolean(!selectedProfilePack.lockCi),
+    };
+  }
+
+  if (selectedProfile.lockCi) {
+    return {
+      value: selectedProfile.defaultCi,
+      shouldAsk: false,
+    };
+  }
+
+  return {
+    value: selectedProfile.defaultCi,
+    shouldAsk: true,
+  };
+}
+
 async function askStackSelection(promptMessage, selectableStackFileNames, userInterface) {
   const stackDisplayChoices = selectableStackFileNames.map((stackFileName) => toTitleCase(stackFileName));
   const selectedDisplayChoice = await askChoice(promptMessage, stackDisplayChoices, userInterface);
@@ -242,8 +317,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
   const wasDirectoryEffectivelyEmpty = await isDirectoryEffectivelyEmpty(resolvedTargetDirectoryPath);
   const hadExistingProjectDocsBeforeInit = await hasExistingProjectDocs(resolvedTargetDirectoryPath);
 
-  await createBackup(resolvedTargetDirectoryPath);
-
   const userInterface = createInterface({ input: stdin, output: stdout });
 
   try {
@@ -442,20 +515,21 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     let selectedAdditionalBlueprintFileNames = [];
     let detectedSetupWasApplied = false;
     let selectedProjectScopeKey = 'both';
-    let selectedProjectScopeLabel = PROJECT_SCOPE_CHOICES.find(
-      (scopeChoice) => scopeChoice.key === 'both'
-    )?.label || 'Both (frontend + backend)';
-
+    let selectedProjectScopeLabel = resolveProjectScopeLabelFromKey('both');
     let architectureRecommendation = null;
-    let architectureProjectDescription = '';
-    let architectPreferenceState = await readArchitectPreferenceState();
-    let architectPreferenceUpdated = false;
-
-    const shouldRunArchitectureRecommendation = !selectedStackFileNameFromOption
-      && !selectedPreset?.stack
-      && !shouldAutoApplyDetectedStack
-      && !selectedProfilePack?.defaultStackFileName
-      && !selectedProfile.defaultStackFileName;
+    let architectureProjectDescription = String(initOptions.projectDescription || '').trim();
+    let discoveryAnswers = null;
+    const ciGuardrailsSelection = resolveSilentCiGuardrailsDefault({
+      initOptions,
+      selectedPreset,
+      selectedProfilePack,
+      selectedProfile,
+    });
+    const isFreshProjectTarget = !projectDetection.hasExistingProjectFiles
+      && wasDirectoryEffectivelyEmpty
+      && !hadExistingProjectDocsBeforeInit;
+    const shouldRunInteractiveScaffolding = isInteractiveSession
+      && (initOptions.scaffoldDocs === true || (initOptions.scaffoldDocs !== false && isFreshProjectTarget));
 
     const detectedSetupDecision = await resolveDetectedSetupDecision({
       shouldAutoApplyDetectedStack,
@@ -479,37 +553,76 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     selectedAdditionalStackFileNames = detectedSetupDecision.selectedAdditionalStackFileNames;
     detectedBlueprintFileName = detectedSetupDecision.detectedBlueprintFileName;
 
-    const architectureSelection = await resolveArchitectureSelection({
-      shouldRunArchitectureRecommendation,
-      initOptions: {
-        ...initOptions,
-        targetDirectoryPath: resolvedTargetDirectoryPath,
+    if (initOptions.projectConfig) {
+      discoveryAnswers = await loadProjectConfig(initOptions.projectConfig);
+      console.log(`\nLoaded project configuration from: ${initOptions.projectConfig}`);
+    } else if (shouldRunInteractiveScaffolding) {
+      discoveryAnswers = await runProjectDiscovery(userInterface, {
+        defaultProjectName: path.basename(resolvedTargetDirectoryPath),
+        defaultProjectDescription: architectureProjectDescription,
+        defaultIncludeCiGuardrails: ciGuardrailsSelection.value,
+        askForCiGuardrails: ciGuardrailsSelection.shouldAsk,
+      });
+    } else if (initOptions.scaffoldDocs === true && !isInteractiveSession) {
+      throw new Error('Non-interactive scaffolding requires --project-config when --scaffold-docs is enabled.');
+    }
+
+    if (discoveryAnswers?.projectDescription) {
+      architectureProjectDescription = discoveryAnswers.projectDescription;
+    }
+
+    if (discoveryAnswers) {
+      selectedProjectScopeKey = inferProjectScopeFromDiscoveryAnswers(discoveryAnswers);
+      selectedProjectScopeLabel = resolveProjectScopeLabelFromKey(selectedProjectScopeKey);
+    }
+
+    const shouldUseSilentArchitectureSelection = !selectedStackFileNameFromOption
+      && !selectedPreset?.stack
+      && !shouldAutoApplyDetectedStack
+      && !selectedProfilePack?.defaultStackFileName
+      && !selectedProfile.defaultStackFileName;
+
+    if (shouldUseSilentArchitectureSelection) {
+      const architectureScopeStackCandidates = filterStackFileNamesByCandidates(
+        stackFileNames,
+        resolveScopeStackCandidates(selectedProjectScopeKey)
+      );
+      const architectureScopeBlueprintCandidates = filterBlueprintFileNamesByCandidates(
+        blueprintFileNames,
+        resolveScopeBlueprintCandidates(selectedProjectScopeKey)
+      );
+
+      architectureRecommendation = recommendArchitecture({
+        projectDescription: architectureProjectDescription || `A software project named ${path.basename(resolvedTargetDirectoryPath)}.`,
+        projectDetection,
+        stackFileNames: architectureScopeStackCandidates,
+        blueprintFileNames: architectureScopeBlueprintCandidates,
+        tokenBudget: initOptions.architectTokenBudget,
+        timeoutMs: initOptions.architectTimeoutMs,
         researchMode: initOptions.architectResearchMode,
         enableRealtimeResearch: initOptions.enableRealtimeResearch,
-      },
-      projectDetection,
-      stackFileNames,
-      blueprintFileNames,
-      userInterface,
-      isInteractiveSession,
-      initialSelectedProjectScopeKey: selectedProjectScopeKey,
-      initialSelectedProjectScopeLabel: selectedProjectScopeLabel,
-      initialSelectedManualStackFileName: selectedManualStackFileName,
-      initialSelectedManualBlueprintFileName: selectedManualBlueprintFileName,
-      architectPreferenceState,
-      askStackSelection,
-      askBlueprintSelection,
-      detectionTransparency,
-    });
+        realtimeSignalFilePath: initOptions.architectRealtimeSignalFile,
+      });
 
-    selectedProjectScopeKey = architectureSelection.selectedProjectScopeKey;
-    selectedProjectScopeLabel = architectureSelection.selectedProjectScopeLabel;
-    selectedManualStackFileName = architectureSelection.selectedManualStackFileName;
-    selectedManualBlueprintFileName = architectureSelection.selectedManualBlueprintFileName;
-    architectureProjectDescription = architectureSelection.architectureProjectDescription;
-    architectureRecommendation = architectureSelection.architectureRecommendation;
-    architectPreferenceState = architectureSelection.architectPreferenceState;
-    architectPreferenceUpdated = architectureSelection.architectPreferenceUpdated;
+      architectureRecommendation.projectDomain = {
+        key: selectedProjectScopeKey,
+        label: selectedProjectScopeLabel,
+      };
+      architectureRecommendation.userVeto = {
+        applied: false,
+        selectedStackFileName: architectureRecommendation.recommendedStackFileName,
+        selectedBlueprintFileName: architectureRecommendation.recommendedBlueprintFileName,
+        source: projectDetection.hasExistingProjectFiles ? 'silent-existing-bootstrap' : 'silent-fresh-bootstrap',
+      };
+
+      selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
+      selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
+
+      if (!projectDetection.hasExistingProjectFiles) {
+        detectionTransparency.quickConfirmation.response = 'fresh-project-streamlined';
+        detectionTransparency.decision.mode = 'fresh-project-streamlined';
+      }
+    }
 
     const blueprintDisplayChoices = blueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName));
 
@@ -550,15 +663,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     if (architectureRecommendation) {
       architectureRecommendation.appliedStackFileName = selectedResolvedStackFileName;
       architectureRecommendation.appliedBlueprintFileName = selectedResolvedBlueprintFileName;
-
-      if (!architectureRecommendation.userVeto) {
-        architectureRecommendation.userVeto = {
-          applied: false,
-          selectedStackFileName: selectedResolvedStackFileName,
-          selectedBlueprintFileName: selectedResolvedBlueprintFileName,
-          source: 'recommendation',
-        };
-      }
     }
 
     const derivedAdditionalBlueprintFileNames = deriveAdditionalBlueprintFileNamesFromStacks(
@@ -580,23 +684,25 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     detectionTransparency.decision.selectedAdditionalBlueprintFileNames = selectedAdditionalBlueprintFileNames;
     detectionTransparency.decision.usedDetectedSetup = detectedSetupWasApplied;
 
-    const includeCiGuardrails = typeof initOptions.ci === 'boolean'
-      ? initOptions.ci
-      : typeof selectedPreset?.ci === 'boolean'
-        ? selectedPreset.ci
-      : selectedProfilePack?.lockCi
-        ? selectedProfilePack.defaultCi
-        : typeof selectedProfilePack?.defaultCi === 'boolean'
-          ? selectedProfilePack.defaultCi
-      : selectedProfile.lockCi
-        ? selectedProfile.defaultCi
-        : await askYesNo('Enable CI/CD quality checks (guardrails) and the LLM Judge policy?', userInterface, selectedProfile.defaultCi);
+    const includeCiGuardrails = typeof discoveryAnswers?.includeCiGuardrails === 'boolean'
+      ? discoveryAnswers.includeCiGuardrails
+      : ciGuardrailsSelection.shouldAsk
+        ? (!isInteractiveSession
+          ? ciGuardrailsSelection.value
+          : await askYesNo(
+            'Enable CI/CD quality checks (guardrails) and the LLM Judge policy?',
+            userInterface,
+            ciGuardrailsSelection.value
+          ))
+        : ciGuardrailsSelection.value;
 
     detectionTransparency.activeRulesSummary.ciGuardrailsEnabled = includeCiGuardrails;
 
     detectionTransparency.decision.selectedProjectScopeKey = selectedProjectScopeKey;
     detectionTransparency.decision.selectedProjectScopeLabel = selectedProjectScopeLabel;
 
+    await createBackup(resolvedTargetDirectoryPath);
+
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,
     });
@@ -629,83 +735,50 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     // --- Project Documentation Scaffolding ---
     let scaffoldingResult = null;
     const supplementalMaterializedDocFileNames = [];
-    const isFreshProjectTarget = wasDirectoryEffectivelyEmpty && !hadExistingProjectDocsBeforeInit;
-    const shouldOfferScaffolding = initOptions.scaffoldDocs === true
-      || Boolean(initOptions.projectConfig)
-      || (initOptions.scaffoldDocs !== false && isFreshProjectTarget);
-
-    if (shouldOfferScaffolding) {
-      if (initOptions.scaffoldDocs === true && !initOptions.projectConfig && !isInteractiveSession) {
-        throw new Error('Non-interactive scaffolding requires --project-config when --scaffold-docs is enabled.');
+    if (discoveryAnswers) {
+      const normalizedConfigDocsLanguage = normalizeDocsLanguage(discoveryAnswers.docsLang || '');
+      if (discoveryAnswers.docsLang && !normalizedConfigDocsLanguage) {
+        throw new Error(`Unsupported docs language in project config: ${discoveryAnswers.docsLang}. Supported values: en, id`);
       }
 
-      const userWantsScaffolding = initOptions.scaffoldDocs === true
-        || initOptions.projectConfig
-        || (!isInteractiveSession
-          ? false
-          : await askYesNo(
-            'This is a fresh project. Want me to scaffold project documentation (architecture, database, API contract, flow)?',
-            userInterface,
-            true
-          ));
+      // Keep generated docs in English by default to align with the writing scope.
+      // A different output language is only used when explicitly requested via --docs-lang.
+      const selectedDocsLanguage = initOptions.docsLang;
 
-      if (userWantsScaffolding) {
-        let discoveryAnswers;
+      if (!initOptions.docsLangProvided && normalizedConfigDocsLanguage && normalizedConfigDocsLanguage !== 'en') {
+        console.log('[INFO] Project config docsLang is set, but output defaults to English. Use --docs-lang to override.');
+      }
 
-        if (initOptions.projectConfig) {
-          discoveryAnswers = await loadProjectConfig(initOptions.projectConfig);
-          console.log(`\nLoaded project configuration from: ${initOptions.projectConfig}`);
-        } else {
-          discoveryAnswers = await runProjectDiscovery(userInterface, {
-            defaultProjectName: path.basename(resolvedTargetDirectoryPath),
-            defaultProjectDescription: architectureProjectDescription,
-          });
+      scaffoldingResult = await generateProjectDocumentation(
+        resolvedTargetDirectoryPath,
+        discoveryAnswers,
+        {
+          stackFileName: selectedResolvedStackFileName,
+          additionalStackFileNames: selectedAdditionalStackFileNames,
+          blueprintFileName: selectedResolvedBlueprintFileName,
+          additionalBlueprintFileNames: selectedAdditionalBlueprintFileNames,
+          runtimeEnvironmentKey: selectedRuntimeEnvironmentKey,
+          runtimeEnvironmentLabel: resolveRuntimeEnvironmentLabelFromKey(selectedRuntimeEnvironmentKey),
+          architectureRecommendation,
+        },
+        {
+          docsLanguage: selectedDocsLanguage,
         }
+      );
 
-        const normalizedConfigDocsLanguage = normalizeDocsLanguage(discoveryAnswers.docsLang || '');
-        if (discoveryAnswers.docsLang && !normalizedConfigDocsLanguage) {
-          throw new Error(`Unsupported docs language in project config: ${discoveryAnswers.docsLang}. Supported values: en, id`);
+      if (scaffoldingResult.bootstrapMode === 'ai-synthesis') {
+        console.log(`\nAI synthesis bootstrap prompts generated in .agent-context/prompts/:`);
+        for (const generatedPromptFileName of scaffoldingResult.generatedPromptFileNames || []) {
+          console.log(`  - .agent-context/prompts/${generatedPromptFileName}`);
         }
-
-        // Keep generated docs in English by default to align with the writing scope.
-        // A different output language is only used when explicitly requested via --docs-lang.
-        const selectedDocsLanguage = initOptions.docsLang;
-
-        if (!initOptions.docsLangProvided && normalizedConfigDocsLanguage && normalizedConfigDocsLanguage !== 'en') {
-          console.log('[INFO] Project config docsLang is set, but output defaults to English. Use --docs-lang to override.');
+        for (const materializedFileName of scaffoldingResult.materializedFileNames || []) {
+          console.log(`  - docs/${materializedFileName}`);
         }
-
-        scaffoldingResult = await generateProjectDocumentation(
-          resolvedTargetDirectoryPath,
-          discoveryAnswers,
-          {
-            stackFileName: selectedResolvedStackFileName,
-            additionalStackFileNames: selectedAdditionalStackFileNames,
-            blueprintFileName: selectedResolvedBlueprintFileName,
-            additionalBlueprintFileNames: selectedAdditionalBlueprintFileNames,
-            runtimeEnvironmentKey: selectedRuntimeEnvironmentKey,
-            runtimeEnvironmentLabel: resolveRuntimeEnvironmentLabelFromKey(selectedRuntimeEnvironmentKey),
-            architectureRecommendation,
-          },
-          {
-            docsLanguage: selectedDocsLanguage,
-          }
-        );
-
-        if (scaffoldingResult.bootstrapMode === 'ai-synthesis') {
-          console.log(`\nAI synthesis bootstrap prompts generated in .agent-context/prompts/:`);
-          for (const generatedPromptFileName of scaffoldingResult.generatedPromptFileNames || []) {
-            console.log(`  - .agent-context/prompts/${generatedPromptFileName}`);
-          }
-          for (const materializedFileName of scaffoldingResult.materializedFileNames || []) {
-            console.log(`  - docs/${materializedFileName}`);
-          }
-          console.log('Project docs will be authored dynamically by your IDE assistant from these prompts.');
-        } else {
-          console.log(`\nProject documentation generated in docs/:`);
-          for (const generatedFileName of scaffoldingResult.generatedFileNames) {
-            console.log(`  - docs/${generatedFileName}`);
-          }
+        console.log('Project docs will be authored dynamically by your IDE assistant from these prompts.');
+      } else {
+        console.log(`\nProject documentation generated in docs/:`);
+        for (const generatedFileName of scaffoldingResult.generatedFileNames) {
+          console.log(`  - docs/${generatedFileName}`);
         }
       }
     }
@@ -795,10 +868,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       uiScopeSignals: existingProjectUiScopeSignals,
     });
 
-    if (architectPreferenceUpdated && architectPreferenceState) {
-      await writeArchitectPreferenceState(architectPreferenceState);
-    }
-
     console.log('\nInitialization complete.');
     console.log(`- Target directory: ${resolvedTargetDirectoryPath}`);
     console.log(`- Profile: ${selectedProfile.displayName}`);
@@ -808,18 +877,8 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     if (selectedProfilePack) {
       console.log(`- Team profile pack: ${selectedProfilePack.displayName}`);
     }
-    if (architectureRecommendation) {
-      console.log(
-        `- Architect recommendation: ${toTitleCase(architectureRecommendation.recommendedStackFileName)} + ${toTitleCase(architectureRecommendation.recommendedBlueprintFileName)} (${architectureRecommendation.confidenceLabel})`
-      );
-      if (!projectDetection.hasExistingProjectFiles) {
-        console.log(`- Project domain: ${selectedProjectScopeLabel}`);
-      }
-      if (architectureRecommendation.userVeto?.applied) {
-        console.log(
-          `- User veto path: applied (${toTitleCase(architectureRecommendation.userVeto.selectedStackFileName)} + ${toTitleCase(architectureRecommendation.userVeto.selectedBlueprintFileName)})`
-        );
-      }
+    if (!projectDetection.hasExistingProjectFiles) {
+      console.log(`- Project domain: ${selectedProjectScopeLabel}`);
     }
     console.log(`- Stack: ${toTitleCase(selectedResolvedStackFileName)}`);
     if (selectedAdditionalStackFileNames.length > 0) {
@@ -833,7 +892,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- CI/CD quality checks (guardrails): ${includeCiGuardrails ? 'enabled' : 'disabled'}`);
     console.log(`- Blocking severities: ${formatBlockingSeverities(selectedProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
-    console.log('- Generated files: .agent-instructions.md, .cursorrules, .windsurfrules, .clauderc, and .agent-context/state/onboarding-report.json');
+    console.log('- Generated files: .instructions.md, .agent-instructions.md, compiled adapters, and .agent-context/state/onboarding-report.json');
     if (scaffoldingResult?.bootstrapMode === 'ai-synthesis') {
       console.log(`- Bootstrap prompts: ${(scaffoldingResult.generatedPromptFileNames || []).length} files generated in .agent-context/prompts/`);
       if ((scaffoldingResult.materializedFileNames || []).length > 0) {

package/lib/cli/commands/upgrade.mjs

@@ -33,6 +33,7 @@ import {
 } from '../detector.mjs';
 import {
   buildCompiledRulesContent,
+  compileDynamicContext,
   writeSelectedPolicy,
   writeOnboardingReport,
   loadOnboardingReportIfExists,
@@ -408,8 +409,15 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         supplementalCreatedFileNames.push('docs/design-intent.json');
       }
 
-      await fs.writeFile(currentRulesPath, plannedRulesContent, 'utf8');
-      await fs.writeFile(path.join(resolvedTargetDirectoryPath, '.windsurfrules'), plannedRulesContent, 'utf8');
+      await compileDynamicContext({
+        targetDirectoryPath: resolvedTargetDirectoryPath,
+        selectedProfileName,
+        selectedStackFileName,
+        selectedAdditionalStackFileNames,
+        selectedBlueprintFileName,
+        selectedAdditionalBlueprintFileNames,
+        includeCiGuardrails,
+      });
       await writeSelectedPolicy(resolvedTargetDirectoryPath, selectedProfileName);
 
       const setupDurationMs = Date.now() - setupStartedAt;
@@ -452,7 +460,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         supplementalCreatedFileNames.forEach((fileName) => console.log(`  [NEW]     ${fileName} (seed)`));
       }
 
-      console.log('\nRefreshed files: .cursorrules, .windsurfrules, .agent-context/state/onboarding-report.json');
+      console.log('\nRefreshed files: .instructions.md, .agent-instructions.md, compiled adapters, and .agent-context/state/onboarding-report.json');
     } catch (error) {
       console.error('\n[FATAL] An error occurred during upgrade. Attempting automatic rollback...');
       try {

package/lib/cli/compiler.mjs

@@ -188,8 +188,8 @@ export async function buildCompiledRulesContent({
       `6. .agent-context/policies/${POLICY_FILE_NAME}`,
       '7. docs/ project context (or bootstrap prompts when docs are not materialized)',
       '',
-      'Primary entrypoint: .agent-instructions.md',
-      'Adapter entrypoints: .cursorrules, .windsurfrules, .clauderc, .gemini/instructions.md, .github/copilot-instructions.md',
+      'Project-specific compiled snapshot: .agent-instructions.md',
+      'Compiled adapter entrypoints: .cursorrules, .windsurfrules, .clauderc, .gemini/instructions.md, .github/copilot-instructions.md',
       'Canonical baseline: .instructions.md',
     ].join('\n')
   );
@@ -396,9 +396,15 @@ export async function buildCompiledRulesContent({
         ...projectDocsEntries.map((docFileName, docIndex) => `${docIndex + 1}. docs/${docFileName}`),
         '',
         'Universal SOP hard block policy:',
+        '- Stop implementation if docs/project-brief.md is missing.',
         '- Stop implementation if docs/architecture-decision-record.md (alias: docs/Architecture-Decision-Record.md) is missing.',
+        '- Stop implementation if docs/flow-overview.md is missing.',
+        '- If the product uses persistent data, docs/database-schema.md must exist before coding continues.',
+        '- If the product exposes API or web application flows, docs/api-contract.md must exist before coding continues.',
         '- For UI scope, stop implementation if docs/DESIGN.md or docs/design-intent.json is missing.',
         '- Materialize missing docs first, then continue coding.',
+        '- Bootstrap missing docs from real repo evidence and the latest user request. Do not write generic placeholder templates.',
+        '- Separate confirmed facts from assumptions and end each major explanation with the next validation action.',
         '',
         'These docs were generated during project initialization and reflect the architecture,',
         'database design, API contracts, and application flows chosen for this project.',
@@ -428,10 +434,15 @@ export async function buildCompiledRulesContent({
         '',
         'Bootstrap policy:',
         '- Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
+        '- docs/flow-overview.md must also exist before coding continues.',
+        '- Add docs/database-schema.md when persistent data is involved.',
+        '- Add docs/api-contract.md when API or web application flows are involved.',
         '- If docs/project-brief.md is missing, execute bootstrap-project-context prompt immediately.',
         hasBootstrapDesignPrompt
           ? '- For UI scope: if docs/DESIGN.md or docs/design-intent.json is missing, execute bootstrap-design prompt before implementing UI surfaces.'
           : '- For UI scope: add a design bootstrap prompt before implementing UI surfaces.',
+        '- Bootstrap docs from repo evidence and the latest user request. Do not use generic placeholder templates.',
+        '- Separate confirmed facts from assumptions, include an Assumptions to Validate section when context is incomplete, and end with the next validation action.',
         '- Save generated docs under docs/ and keep them updated when feature scope changes.',
         'Latest user prompt defines current feature scope and product direction.',
         'Treat synthesized docs as living references, then continue implementation with those docs as source of truth.',

package/lib/cli/detector.mjs

@@ -100,6 +100,24 @@ const PROJECT_MARKER_FILE_NAMES = new Set([
   'tsconfig.json',
   ...DIRECT_UI_MARKER_NAMES,
 ]);
+const INTERNAL_GOVERNANCE_SURFACE_NAMES = new Set([
+  '.agent-context',
+  '.agent-instructions.md',
+  '.agent-override.md',
+  '.agentic-backup',
+  '.agents',
+  '.clauderc',
+  '.cursorrules',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.instructions.md',
+  '.vscode',
+  '.windsurfrules',
+  '.zed',
+  'AGENTS.md',
+  'mcp.json',
+]);
 
 function looksLikeWorkspaceSearchCandidate(directoryName) {
   const normalizedDirectoryName = String(directoryName || '').trim().toLowerCase();
@@ -148,6 +166,10 @@ export async function collectProjectMarkers(targetDirectoryPath) {
       continue;
     }
 
+    if (INTERNAL_GOVERNANCE_SURFACE_NAMES.has(directoryEntry.name)) {
+      continue;
+    }
+
     markerNames.add(directoryEntry.name);
   }