@ryuenn3123/agentic-senior-core 2.5.18 → 2.5.20

package/lib/cli/commands/init.mjs

@@ -65,6 +65,7 @@ import { evaluateSkillDomainCompatibility } from '../compatibility.mjs';
 import {
   ARCHITECT_DEFAULT_TOKEN_BUDGET,
   ARCHITECT_DEFAULT_TIMEOUT_MS,
+  ARCHITECT_DEFAULT_RESEARCH_MODE,
   ARCHITECT_MIN_TOKEN_BUDGET,
   ARCHITECT_MAX_TOKEN_BUDGET,
   ARCHITECT_MIN_TIMEOUT_MS,
@@ -100,6 +101,9 @@ export function parseInitArguments(commandArguments) {
     projectDescription: '',
     architectTokenBudget: ARCHITECT_DEFAULT_TOKEN_BUDGET,
     architectTimeoutMs: ARCHITECT_DEFAULT_TIMEOUT_MS,
+    architectResearchMode: ARCHITECT_DEFAULT_RESEARCH_MODE,
+    enableRealtimeResearch: false,
+    architectRealtimeSignalFile: null,
     runtimeEnv: 'auto',
     runtimeEnvProvided: false,
   };
@@ -308,6 +312,38 @@ export function parseInitArguments(commandArguments) {
       continue;
     }
 
+    if (currentArgument === '--architect-research-mode') {
+      parsedInitOptions.architectResearchMode = commandArguments[argumentIndex + 1] || ARCHITECT_DEFAULT_RESEARCH_MODE;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-research-mode=')) {
+      parsedInitOptions.architectResearchMode = currentArgument.split('=')[1] || ARCHITECT_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;
@@ -350,9 +386,18 @@ export function parseInitArguments(commandArguments) {
     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 || ARCHITECT_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;
 }
@@ -502,6 +547,14 @@ async function askBlueprintSelection(promptMessage, selectableBlueprintFileNames
   return selectableBlueprintFileNames[selectedIndex] || selectableBlueprintFileNames[0] || null;
 }
 
+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 runInitCommand(targetDirectoryArgument, initOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
   const isTokenOptimizationEnabled = typeof initOptions.tokenOptimize === 'boolean'
@@ -654,6 +707,64 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`\nSelected profile: ${selectedProfile.displayName}`);
     console.log(`This profile will block these review severities in CI: ${formatBlockingSeverities(selectedProfile.blockingSeverities)}.`);
 
+    const detectionMajorConstraints = buildExistingProjectMajorConstraints();
+    const detectionTransparency = {
+      declaredAt: new Date().toISOString(),
+      declarationType: projectDetection.hasExistingProjectFiles ? 'existing-project' : 'fresh-project',
+      declarationShown: projectDetection.hasExistingProjectFiles,
+      detectionSummary: projectDetection.hasExistingProjectFiles
+        ? buildDetectionSummary(projectDetection)
+        : 'No existing project markers were detected.',
+      activeRulesSummary: {
+        canonicalSource: '.instructions.md',
+        compiledEntrypoints: ['.cursorrules', '.windsurfrules'],
+        stackLoadingMode: 'lazy',
+        selectedProfile: selectedProfileName,
+        selectedProfileDisplayName: selectedProfile.displayName,
+        blockingSeverities: selectedProfile.blockingSeverities,
+        ciGuardrailsEnabled: null,
+      },
+      majorConstraints: detectionMajorConstraints,
+      quickConfirmation: {
+        offered: false,
+        response: projectDetection.hasExistingProjectFiles ? 'pending' : 'not-applicable',
+        source: 'existing-project-detection',
+      },
+      decision: {
+        mode: projectDetection.hasExistingProjectFiles ? 'pending' : 'fresh-directory',
+        selectedStackFileName: null,
+        selectedBlueprintFileName: null,
+      },
+    };
+
+    if (projectDetection.hasExistingProjectFiles) {
+      console.log('\nExisting project detection transparency:');
+
+      if (projectDetection.recommendedStackFileName) {
+        const confidenceScoreLabel = Number(projectDetection.confidenceScore || 0).toFixed(2);
+        console.log(
+          `- Detected stack: ${toTitleCase(projectDetection.recommendedStackFileName)} (${projectDetection.confidenceLabel}, score ${confidenceScoreLabel})`
+        );
+
+        if (projectDetection.secondaryStackFileNames?.length) {
+          console.log(
+            `- Secondary stack signals: ${projectDetection.secondaryStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}`
+          );
+        }
+      } else {
+        console.log('- Detected stack: unresolved (insufficient markers).');
+      }
+
+      console.log('- Active rules baseline: canonical .instructions.md -> compiled .cursorrules/.windsurfrules');
+      console.log(
+        `- Active review profile: ${selectedProfile.displayName} (blocking severities: ${formatBlockingSeverities(selectedProfile.blockingSeverities)})`
+      );
+      console.log('- Major constraints:');
+      for (const majorConstraint of detectionMajorConstraints) {
+        console.log(`  - ${majorConstraint}`);
+      }
+    }
+
     if (selectedProfilePack) {
       console.log(`Applying team profile pack: ${selectedProfilePack.displayName}.`);
       console.log(`Pack defaults: stack ${toTitleCase(selectedProfilePack.defaultStackFileName)}, blueprint ${toTitleCase(selectedProfilePack.defaultBlueprintFileName)}.`);
@@ -667,11 +778,15 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       && !selectedStackFileNameFromOption
       && !selectedPreset?.stack
       && !selectedProfilePack?.defaultStackFileName;
+    const detectedBlueprintFileName = projectDetection.recommendedBlueprintFileName
+      || BLUEPRINT_RECOMMENDATIONS[projectDetection.recommendedStackFileName]
+      || null;
 
     let selectedManualStackFileName = null;
     let selectedManualBlueprintFileName = null;
     let selectedAdditionalStackFileNames = [];
     let selectedAdditionalBlueprintFileNames = [];
+    let detectedSetupWasApplied = false;
 
     let architectureRecommendation = null;
     let architectPreferenceState = await readArchitectPreferenceState();
@@ -684,11 +799,73 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       && !selectedProfile.defaultStackFileName;
 
     if (shouldAutoApplyDetectedStack) {
-      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(', ')}.`);
+      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 || [];
       }
-      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';
     }
 
     if (shouldRunArchitectureRecommendation) {
@@ -711,6 +888,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         blueprintFileNames,
         tokenBudget: initOptions.architectTokenBudget,
         timeoutMs: initOptions.architectTimeoutMs,
+        researchMode: initOptions.architectResearchMode,
+        enableRealtimeResearch: initOptions.enableRealtimeResearch,
+        realtimeSignalFilePath: initOptions.architectRealtimeSignalFile,
       });
 
       architectureRecommendation.userVeto = {
@@ -805,10 +985,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
 
     const selectedResolvedStackFileName = selectedStackFileNameFromOption
       || selectedPreset?.stack
-      || (shouldAutoApplyDetectedStack ? projectDetection.recommendedStackFileName : null)
+      || selectedManualStackFileName
+      || (detectedSetupWasApplied ? projectDetection.recommendedStackFileName : null)
       || selectedProfilePack?.defaultStackFileName
       || selectedProfile.defaultStackFileName
-      || selectedManualStackFileName
       || stackFileNames[0];
 
     selectedAdditionalStackFileNames = normalizeAdditionalStackSelection(
@@ -816,9 +996,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       selectedAdditionalStackFileNames
     );
 
-    const recommendedBlueprintFileName = projectDetection.recommendedBlueprintFileName
-      && shouldAutoApplyDetectedStack
-      ? projectDetection.recommendedBlueprintFileName
+    const recommendedBlueprintFileName = detectedSetupWasApplied
+      && detectedBlueprintFileName
+      ? detectedBlueprintFileName
       : BLUEPRINT_RECOMMENDATIONS[selectedResolvedStackFileName] || null;
 
     if (!recommendedBlueprintFileName && !selectedBlueprintFileNameFromOption && !selectedProfile.defaultBlueprintFileName) {
@@ -864,6 +1044,12 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         : derivedAdditionalBlueprintFileNames
     );
 
+    detectionTransparency.decision.selectedStackFileName = selectedResolvedStackFileName;
+    detectionTransparency.decision.selectedBlueprintFileName = selectedResolvedBlueprintFileName;
+    detectionTransparency.decision.selectedAdditionalStackFileNames = selectedAdditionalStackFileNames;
+    detectionTransparency.decision.selectedAdditionalBlueprintFileNames = selectedAdditionalBlueprintFileNames;
+    detectionTransparency.decision.usedDetectedSetup = detectedSetupWasApplied;
+
     const selectedSkillDomainNames = inferSkillDomainNamesFromSelection(
       selectedResolvedStackFileName,
       selectedResolvedBlueprintFileName,
@@ -883,6 +1069,8 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         ? selectedProfile.defaultCi
         : await askYesNo('Enable CI/CD quality checks (guardrails) and the LLM Judge policy?', userInterface, selectedProfile.defaultCi);
 
+    detectionTransparency.activeRulesSummary.ciGuardrailsEnabled = includeCiGuardrails;
+
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,
     });
@@ -1044,6 +1232,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         stateFile: isMemoryContinuityEnabled ? '.agent-context/state/memory-continuity.json' : null,
       },
       architectRecommendation: architectureRecommendation,
+      detectionTransparency,
     });
 
     if (architectPreferenceUpdated && architectPreferenceState) {

package/lib/cli/commands/upgrade.mjs

@@ -24,7 +24,11 @@ import {
   copyGovernanceAssetsToTarget,
 } from '../utils.mjs';
 
-import { detectProjectContext } from '../detector.mjs';
+import {
+  detectProjectContext,
+  buildDetectionSummary,
+  formatDetectionCandidates,
+} from '../detector.mjs';
 import {
   buildCompiledRulesContent,
   writeSelectedPolicy,
@@ -76,6 +80,14 @@ export function parseUpgradeArguments(commandArguments) {
   return parsedUpgradeOptions;
 }
 
+function buildExistingProjectMajorConstraints() {
+  return [
+    'Preserve existing project markers and avoid forced stack migration.',
+    'Keep stack rule loading lazy and scoped to touched code.',
+    'Upgrade keeps prior onboarding choices unless user overrides them.',
+  ];
+}
+
 export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
 
@@ -143,6 +155,56 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       ? existingOnboardingReport.ciGuardrailsEnabled
       : true;
 
+    const detectionMajorConstraints = buildExistingProjectMajorConstraints();
+    const detectionTransparency = {
+      declaredAt: new Date().toISOString(),
+      declarationType: 'existing-project',
+      declarationShown: true,
+      detectionSummary: buildDetectionSummary(projectDetection),
+      activeRulesSummary: {
+        canonicalSource: '.instructions.md',
+        compiledEntrypoints: ['.cursorrules', '.windsurfrules'],
+        stackLoadingMode: 'lazy',
+        selectedProfile: selectedProfileName,
+        selectedProfileDisplayName: toTitleCase(selectedProfileName),
+        blockingSeverities: PROFILE_PRESETS[selectedProfileName]?.blockingSeverities || [],
+        ciGuardrailsEnabled: includeCiGuardrails,
+      },
+      majorConstraints: detectionMajorConstraints,
+      quickConfirmation: {
+        offered: false,
+        response: 'upgrade-auto',
+        source: 'upgrade-assistant',
+      },
+      decision: {
+        mode: 'upgrade-auto',
+        selectedStackFileName,
+        selectedBlueprintFileName,
+      },
+    };
+
+    console.log('\nExisting project detection transparency:');
+    if (projectDetection.recommendedStackFileName) {
+      const confidenceScoreLabel = Number(projectDetection.confidenceScore || 0).toFixed(2);
+      console.log(
+        `- Detected stack: ${toTitleCase(projectDetection.recommendedStackFileName)} (${projectDetection.confidenceLabel}, score ${confidenceScoreLabel})`
+      );
+    } else {
+      console.log('- Detected stack: unresolved (insufficient markers).');
+    }
+    console.log('- Active rules baseline: canonical .instructions.md -> compiled .cursorrules/.windsurfrules');
+    console.log(
+      `- Active review profile: ${toTitleCase(selectedProfileName)} (blocking severities: ${(
+        PROFILE_PRESETS[selectedProfileName]?.blockingSeverities || []
+      ).join(', ') || 'none'})`
+    );
+    console.log('- Top candidates:');
+    console.log(formatDetectionCandidates(projectDetection.rankedCandidates));
+    console.log('- Major constraints:');
+    for (const majorConstraint of detectionMajorConstraints) {
+      console.log(`  - ${majorConstraint}`);
+    }
+
     const selectedSkillDomainNames = inferSkillDomainNamesFromSelection(
       selectedStackFileName,
       selectedBlueprintFileName,
@@ -249,6 +311,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         compatibilityWarnings,
         runtimeEnvironment: existingOnboardingReport?.runtimeEnvironment || null,
         operationMode: 'upgrade',
+        detectionTransparency,
       });
 
       console.log('\nUpgrade complete.');

package/lib/cli/compiler.mjs

@@ -56,6 +56,7 @@ export async function writeOnboardingReport({
   tokenOptimization = undefined,
   memoryContinuity = undefined,
   architectRecommendation = null,
+  detectionTransparency = null,
 }) {
   const onboardingReportPath = path.join(targetDirectoryPath, '.agent-context', 'state', 'onboarding-report.json');
   const resolvedTokenOptimization = typeof tokenOptimization === 'undefined'
@@ -110,6 +111,7 @@ export async function writeOnboardingReport({
       detectionReasoning: projectDetection.detectionReasoning,
       rankedCandidates: projectDetection.rankedCandidates,
       evidence: projectDetection.evidence,
+      detectionTransparency: detectionTransparency || null,
     },
   };
 

package/lib/cli/utils.mjs

@@ -29,7 +29,7 @@ export function printUsage() {
   console.log('');
   console.log('Usage:');
   console.log('  agentic-senior-core launch');
-  console.log('  agentic-senior-core init [target-directory] [--preset <name>] [--profile <beginner|balanced|strict>] [--profile-pack <name>] [--stack <name>] [--blueprint <name>] [--project-description <text>] [--architect-token-budget <number>] [--architect-timeout-ms <number>] [--ci <true|false>] [--newbie] [--token-optimize] [--no-token-optimize] [--token-agent <name>] [--memory-continuity] [--no-memory-continuity] [--scaffold-docs] [--no-scaffold-docs] [--docs-lang <en|id>] [--project-config <path>] [--runtime-env <auto|linux-wsl|linux|windows|macos>]');
+  console.log('  agentic-senior-core init [target-directory] [--preset <name>] [--profile <beginner|balanced|strict>] [--profile-pack <name>] [--stack <name>] [--blueprint <name>] [--project-description <text>] [--architect-token-budget <number>] [--architect-timeout-ms <number>] [--architect-research-mode <snapshot|realtime>] [--enable-realtime-research] [--architect-realtime-signal-file <path>] [--ci <true|false>] [--newbie] [--token-optimize] [--no-token-optimize] [--token-agent <name>] [--memory-continuity] [--no-memory-continuity] [--scaffold-docs] [--no-scaffold-docs] [--docs-lang <en|id>] [--project-config <path>] [--runtime-env <auto|linux-wsl|linux|windows|macos>]');
   console.log('  agentic-senior-core upgrade [target-directory] [--dry-run] [--yes] [--mcp-template]');
   console.log('  agentic-senior-core optimize [target-directory] [--agent <copilot|claude|cursor|windsurf|gemini|codex|cline>] [--enable|--disable] [--show]');
   console.log('  agentic-senior-core mcp');
@@ -49,6 +49,9 @@ export function printUsage() {
   console.log('  --project-description  Architecture intent text used for stack/blueprint recommendation');
   console.log('  --architect-token-budget  Max token estimate used by recommendation research (default: 900)');
   console.log('  --architect-timeout-ms  Max recommendation research time in milliseconds (default: 1500)');
+  console.log('  --architect-research-mode  Recommendation evidence mode (snapshot or realtime; default: snapshot)');
+  console.log('  --enable-realtime-research  Explicit gate to allow trusted realtime evidence ingestion');
+  console.log('  --architect-realtime-signal-file  Optional JSON payload path for trusted realtime stack/design signals');
   console.log('  --ci         Override CI/CD quality checks (guardrails) (true|false)');
   console.log('  --token-optimize  Explicitly enable token optimization policy during init (default behavior)');
   console.log('  --token-agent     Set token optimization agent target (copilot, claude, cursor, windsurf, gemini, codex, cline)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "2.5.18",
+  "version": "2.5.20",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/validate.mjs

@@ -155,6 +155,54 @@ const REQUIRED_COMPLIANCE_CANONICAL_SNIPPETS = [
     label: 'release operations checklist keeps canonical term Federated Governance',
   },
 ];
+const REQUIRED_DETECTION_TRANSPARENCY_SNIPPETS = [
+  {
+    path: 'lib/cli/commands/init.mjs',
+    snippets: [
+      'Existing project detection transparency:',
+      'Use detected setup for this existing project?',
+      'detectionTransparency',
+    ],
+  },
+  {
+    path: 'lib/cli/commands/upgrade.mjs',
+    snippets: [
+      'Existing project detection transparency:',
+      'formatDetectionCandidates(projectDetection.rankedCandidates)',
+      'detectionTransparency',
+    ],
+  },
+  {
+    path: 'lib/cli/compiler.mjs',
+    snippets: [
+      'detectionTransparency = null',
+      'detectionTransparency: detectionTransparency || null',
+    ],
+  },
+];
+const REQUIRED_STACK_RESEARCH_ENGINE_SNIPPETS = [
+  {
+    path: 'lib/cli/architect.mjs',
+    snippets: [
+      'ARCHITECT_RESEARCH_SNAPSHOT_FILE_PATH',
+      'evidenceCitations',
+      'designGuidance',
+      'copiedExternalProse: false',
+      'realtimeGateEnabled',
+      'requestedMode: requestedResearchMode',
+    ],
+  },
+  {
+    path: 'lib/cli/commands/init.mjs',
+    snippets: [
+      '--architect-research-mode',
+      '--enable-realtime-research',
+      '--architect-realtime-signal-file',
+      'researchMode: initOptions.architectResearchMode',
+      'enableRealtimeResearch: initOptions.enableRealtimeResearch',
+    ],
+  },
+];
 
 const validationResult = {
   passed: 0,
@@ -275,6 +323,7 @@ async function validateRequiredFiles() {
     '.agent-context/state/benchmark-reproducibility.json',
     '.agent-context/state/benchmark-writer-judge-config.json',
     '.agent-context/state/benchmark-watchlist.json',
+    '.agent-context/state/stack-research-snapshot.json',
     '.agent-context/state/memory-schema-v1.json',
     '.agent-context/state/memory-adapter-contract.json',
     '.agent-context/state/skill-platform.json',
@@ -928,6 +977,115 @@ async function validateTerminologyMapping() {
   }
 }
 
+async function validateDetectionTransparencyCoverage() {
+  console.log('\nChecking existing-project detection transparency coverage...');
+
+  for (const transparencyRule of REQUIRED_DETECTION_TRANSPARENCY_SNIPPETS) {
+    const absoluteTransparencyPath = join(ROOT_DIR, transparencyRule.path);
+
+    if (!(await fileExists(absoluteTransparencyPath))) {
+      fail(`Missing detection transparency source: ${transparencyRule.path}`);
+      continue;
+    }
+
+    const transparencyContent = await readTextFile(absoluteTransparencyPath);
+    for (const requiredSnippet of transparencyRule.snippets) {
+      if (transparencyContent.includes(requiredSnippet)) {
+        pass(`${transparencyRule.path} includes detection transparency snippet: ${requiredSnippet}`);
+      } else {
+        fail(`${transparencyRule.path} is missing detection transparency snippet: ${requiredSnippet}`);
+      }
+    }
+  }
+}
+
+async function validateStackResearchEngineCoverage() {
+  console.log('\nChecking stack research engine coverage...');
+
+  for (const coverageRule of REQUIRED_STACK_RESEARCH_ENGINE_SNIPPETS) {
+    const absoluteCoveragePath = join(ROOT_DIR, coverageRule.path);
+
+    if (!(await fileExists(absoluteCoveragePath))) {
+      fail(`Missing stack research source: ${coverageRule.path}`);
+      continue;
+    }
+
+    const coverageContent = await readTextFile(absoluteCoveragePath);
+    for (const requiredSnippet of coverageRule.snippets) {
+      if (coverageContent.includes(requiredSnippet)) {
+        pass(`${coverageRule.path} includes stack research snippet: ${requiredSnippet}`);
+      } else {
+        fail(`${coverageRule.path} is missing stack research snippet: ${requiredSnippet}`);
+      }
+    }
+  }
+}
+
+function isNormalizedMetricValue(value) {
+  return Number.isFinite(Number(value)) && Number(value) >= 0 && Number(value) <= 1;
+}
+
+async function validateStackResearchSnapshotState() {
+  console.log('\nChecking deterministic stack research snapshot state...');
+
+  const snapshotPath = join(ROOT_DIR, '.agent-context', 'state', 'stack-research-snapshot.json');
+  if (!(await fileExists(snapshotPath))) {
+    fail('Missing deterministic stack research snapshot: .agent-context/state/stack-research-snapshot.json');
+    return;
+  }
+
+  let snapshotPayload;
+  try {
+    snapshotPayload = JSON.parse(await readTextFile(snapshotPath));
+  } catch {
+    fail('Invalid JSON in .agent-context/state/stack-research-snapshot.json');
+    return;
+  }
+
+  if (snapshotPayload?.deterministic === true) {
+    pass('stack-research-snapshot.json declares deterministic: true');
+  } else {
+    fail('stack-research-snapshot.json must declare deterministic: true');
+  }
+
+  const generatedAtValue = String(snapshotPayload?.generatedAt || '');
+  if (!Number.isNaN(Date.parse(generatedAtValue))) {
+    pass('stack-research-snapshot.json includes valid generatedAt timestamp');
+  } else {
+    fail('stack-research-snapshot.json must include a valid generatedAt timestamp');
+  }
+
+  if (Array.isArray(snapshotPayload?.trustedRealtimeSources) && snapshotPayload.trustedRealtimeSources.length > 0) {
+    pass('stack-research-snapshot.json includes trustedRealtimeSources');
+  } else {
+    fail('stack-research-snapshot.json must include at least one trustedRealtimeSources entry');
+  }
+
+  if (!Array.isArray(snapshotPayload?.stackSignals) || snapshotPayload.stackSignals.length === 0) {
+    fail('stack-research-snapshot.json must include non-empty stackSignals array');
+    return;
+  }
+
+  pass(`stack-research-snapshot.json includes ${snapshotPayload.stackSignals.length} stack signal entries`);
+
+  const invalidSignalEntries = snapshotPayload.stackSignals.filter((signalEntry) => {
+    const hasStackName = typeof signalEntry?.stackFileName === 'string' && signalEntry.stackFileName.trim().length > 0;
+    const hasMeasuredAt = !Number.isNaN(Date.parse(String(signalEntry?.measuredAt || '')));
+    const metrics = signalEntry?.metrics || {};
+    const hasValidMetrics = isNormalizedMetricValue(metrics.ecosystemMaturity)
+      && isNormalizedMetricValue(metrics.talentAvailability)
+      && isNormalizedMetricValue(metrics.deliveryVelocity);
+
+    return !(hasStackName && hasMeasuredAt && hasValidMetrics);
+  });
+
+  if (invalidSignalEntries.length === 0) {
+    pass('stack-research-snapshot.json stackSignals keep measurable metrics and timestamps');
+  } else {
+    fail(`stack-research-snapshot.json has invalid stackSignals entries: ${invalidSignalEntries.length}`);
+  }
+}
+
 async function validateMcpConfiguration() {
   console.log('\nChecking MCP configuration...');
 
@@ -1177,6 +1335,9 @@ async function main() {
   await validateVersionConsistency();
   await validateDocumentationFlow();
   await validateTerminologyMapping();
+  await validateDetectionTransparencyCoverage();
+  await validateStackResearchEngineCoverage();
+  await validateStackResearchSnapshotState();
   await validateMcpConfiguration();
   await validateHumanWritingGovernance();
   await validateInstructionAdapters();