@ryuenn3123/agentic-senior-core 2.5.19 → 2.5.20

package/.agent-context/state/memory-continuity-benchmark.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-18T02:58:09.480Z",
+  "generatedAt": "2026-04-18T04:27:02.459Z",
   "reportName": "memory-continuity-benchmark",
   "schemaVersion": "1.0.0",
   "passed": true,

package/.agent-context/state/stack-research-snapshot.json

@@ -0,0 +1,112 @@
+{
+  "schemaVersion": "1.0.0",
+  "snapshotId": "ecosystem-signals-2026-04-18",
+  "generatedAt": "2026-04-18T00:00:00.000Z",
+  "deterministic": true,
+  "sourceName": "Agentic-Senior-Core deterministic stack research snapshot",
+  "sourceUrl": "state://stack-research-snapshot/2026-04-18",
+  "trustedRealtimeSources": [
+    {
+      "sourceId": "awwwards-trend-feed",
+      "sourceName": "Awwwards Trend Feed",
+      "sourceUrl": "https://www.awwwards.com"
+    },
+    {
+      "sourceId": "github-ecosystem-signals",
+      "sourceName": "GitHub Ecosystem Signals",
+      "sourceUrl": "https://github.com"
+    }
+  ],
+  "stackSignals": [
+    {
+      "stackFileName": "typescript.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.91,
+        "talentAvailability": 0.9,
+        "deliveryVelocity": 0.89
+      }
+    },
+    {
+      "stackFileName": "python.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.92,
+        "talentAvailability": 0.88,
+        "deliveryVelocity": 0.9
+      }
+    },
+    {
+      "stackFileName": "java.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.89,
+        "talentAvailability": 0.83,
+        "deliveryVelocity": 0.8
+      }
+    },
+    {
+      "stackFileName": "php.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.79,
+        "talentAvailability": 0.75,
+        "deliveryVelocity": 0.84
+      }
+    },
+    {
+      "stackFileName": "go.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.84,
+        "talentAvailability": 0.78,
+        "deliveryVelocity": 0.82
+      }
+    },
+    {
+      "stackFileName": "csharp.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.86,
+        "talentAvailability": 0.8,
+        "deliveryVelocity": 0.79
+      }
+    },
+    {
+      "stackFileName": "rust.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.74,
+        "talentAvailability": 0.63,
+        "deliveryVelocity": 0.67
+      }
+    },
+    {
+      "stackFileName": "ruby.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.7,
+        "talentAvailability": 0.62,
+        "deliveryVelocity": 0.72
+      }
+    },
+    {
+      "stackFileName": "react-native.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.72,
+        "talentAvailability": 0.67,
+        "deliveryVelocity": 0.74
+      }
+    },
+    {
+      "stackFileName": "flutter.md",
+      "measuredAt": "2026-04-18T00:00:00.000Z",
+      "metrics": {
+        "ecosystemMaturity": 0.75,
+        "talentAvailability": 0.69,
+        "deliveryVelocity": 0.76
+      }
+    }
+  ]
+}

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.5.19
+Generated by Agentic-Senior-Core CLI v2.5.20
 Timestamp: 2026-04-18T03:00:00.000Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.5.19
+Generated by Agentic-Senior-Core CLI v2.5.20
 Timestamp: 2026-04-18T03:00:00.000Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/README.md

@@ -36,6 +36,18 @@ Project-description-first path (AI as Architect with veto control):
 npx @ryuenn3123/agentic-senior-core init --project-description "Machine learning API for fraud detection"
 ```
 
+Deterministic stack research mode (default):
+
+```bash
+npx @ryuenn3123/agentic-senior-core init --project-description "Event-driven payments platform" --architect-research-mode snapshot
+```
+
+Optional trusted realtime enrichment (explicitly gated):
+
+```bash
+npx @ryuenn3123/agentic-senior-core init --project-description "Modern conversion-focused product website" --architect-research-mode realtime --enable-realtime-research --architect-realtime-signal-file ./realtime-signals.json
+```
+
 ---
 
 ## Before / After

package/lib/cli/architect.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { BLUEPRINT_RECOMMENDATIONS } from './constants.mjs';
 import { ensureDirectory, pathExists, toTitleCase } from './utils.mjs';
@@ -11,6 +13,98 @@ export const ARCHITECT_MIN_TOKEN_BUDGET = 200;
 export const ARCHITECT_MAX_TOKEN_BUDGET = 4000;
 export const ARCHITECT_MIN_TIMEOUT_MS = 200;
 export const ARCHITECT_MAX_TIMEOUT_MS = 10000;
+export const ARCHITECT_DEFAULT_RESEARCH_MODE = 'snapshot';
+
+const ARCHITECT_ALLOWED_RESEARCH_MODES = new Set(['snapshot', 'realtime']);
+const ARCHITECT_DEFAULT_REALTIME_SIGNAL_ENV_KEY = 'AGENTIC_ARCHITECT_REALTIME_SIGNAL_JSON';
+const ARCHITECT_DEFAULT_REALTIME_SIGNAL_PATH_ENV_KEY = 'AGENTIC_ARCHITECT_REALTIME_SIGNAL_PATH';
+const ARCHITECT_ALLOWED_PALETTE_ROLES = ['base', 'surface', 'accent', 'success', 'danger'];
+const ARCHITECT_ALLOWED_TYPOGRAPHY_SCALES = ['compact', 'balanced', 'expressive'];
+const ARCHITECT_ALLOWED_SPACING_PATTERNS = ['compact-grid', 'balanced-grid', 'airy-grid'];
+const ARCHITECT_ALLOWED_MOTION_CHARACTERISTICS = [
+  'subtle-enter',
+  'staggered-reveal',
+  'state-feedback',
+  'conversion-focus',
+  'calm-transition',
+];
+
+const ARCHITECT_MODULE_FILE_PATH = fileURLToPath(import.meta.url);
+const ARCHITECT_PACKAGE_ROOT = path.resolve(path.dirname(ARCHITECT_MODULE_FILE_PATH), '..', '..');
+const ARCHITECT_RESEARCH_SNAPSHOT_FILE_PATH = path.join(
+  ARCHITECT_PACKAGE_ROOT,
+  '.agent-context',
+  'state',
+  'stack-research-snapshot.json'
+);
+
+const FALLBACK_STACK_RESEARCH_SNAPSHOT = {
+  schemaVersion: '1.0.0',
+  snapshotId: 'ecosystem-signals-fallback',
+  generatedAt: '2026-04-18T00:00:00.000Z',
+  deterministic: true,
+  sourceName: 'Agentic-Senior-Core internal fallback snapshot',
+  sourceUrl: 'state://stack-research-snapshot/fallback',
+  trustedRealtimeSources: [
+    {
+      sourceId: 'awwwards-trend-feed',
+      sourceName: 'Awwwards Trend Feed',
+      sourceUrl: 'https://www.awwwards.com',
+    },
+  ],
+  stackSignals: [
+    {
+      stackFileName: 'typescript.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.91, talentAvailability: 0.9, deliveryVelocity: 0.89 },
+    },
+    {
+      stackFileName: 'python.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.92, talentAvailability: 0.88, deliveryVelocity: 0.9 },
+    },
+    {
+      stackFileName: 'java.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.89, talentAvailability: 0.83, deliveryVelocity: 0.8 },
+    },
+    {
+      stackFileName: 'php.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.79, talentAvailability: 0.75, deliveryVelocity: 0.84 },
+    },
+    {
+      stackFileName: 'go.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.84, talentAvailability: 0.78, deliveryVelocity: 0.82 },
+    },
+    {
+      stackFileName: 'csharp.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.86, talentAvailability: 0.8, deliveryVelocity: 0.79 },
+    },
+    {
+      stackFileName: 'rust.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.74, talentAvailability: 0.63, deliveryVelocity: 0.67 },
+    },
+    {
+      stackFileName: 'ruby.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.7, talentAvailability: 0.62, deliveryVelocity: 0.72 },
+    },
+    {
+      stackFileName: 'react-native.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.72, talentAvailability: 0.67, deliveryVelocity: 0.74 },
+    },
+    {
+      stackFileName: 'flutter.md',
+      measuredAt: '2026-04-18T00:00:00.000Z',
+      metrics: { ecosystemMaturity: 0.75, talentAvailability: 0.69, deliveryVelocity: 0.76 },
+    },
+  ],
+};
 
 const ARCHITECT_PREFERENCE_FILE_PATH = process.env.AGENTIC_ARCHITECT_PREF_FILE
   ? path.resolve(process.env.AGENTIC_ARCHITECT_PREF_FILE)
@@ -140,6 +234,283 @@ function resolveRecommendedBlueprintFileName(stackFileName, blueprintFileNames)
   return blueprintFileNames[0] || null;
 }
 
+function normalizeArchitectResearchMode(rawMode) {
+  const normalizedMode = String(rawMode || ARCHITECT_DEFAULT_RESEARCH_MODE).trim().toLowerCase();
+  if (ARCHITECT_ALLOWED_RESEARCH_MODES.has(normalizedMode)) {
+    return normalizedMode;
+  }
+
+  return ARCHITECT_DEFAULT_RESEARCH_MODE;
+}
+
+function isValidIsoTimestamp(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return false;
+  }
+
+  return !Number.isNaN(Date.parse(value));
+}
+
+function toIsoTimestamp(value, fallbackValue = new Date().toISOString()) {
+  return isValidIsoTimestamp(value) ? new Date(value).toISOString() : fallbackValue;
+}
+
+function loadStackResearchSnapshot() {
+  try {
+    if (!existsSync(ARCHITECT_RESEARCH_SNAPSHOT_FILE_PATH)) {
+      return {
+        snapshot: FALLBACK_STACK_RESEARCH_SNAPSHOT,
+        sourcePath: 'fallback://embedded-snapshot',
+      };
+    }
+
+    const snapshotContent = readFileSync(ARCHITECT_RESEARCH_SNAPSHOT_FILE_PATH, 'utf8');
+    const parsedSnapshot = JSON.parse(snapshotContent);
+
+    if (!Array.isArray(parsedSnapshot?.stackSignals) || parsedSnapshot.stackSignals.length === 0) {
+      return {
+        snapshot: FALLBACK_STACK_RESEARCH_SNAPSHOT,
+        sourcePath: 'fallback://embedded-snapshot',
+      };
+    }
+
+    return {
+      snapshot: parsedSnapshot,
+      sourcePath: ARCHITECT_RESEARCH_SNAPSHOT_FILE_PATH,
+    };
+  } catch {
+    return {
+      snapshot: FALLBACK_STACK_RESEARCH_SNAPSHOT,
+      sourcePath: 'fallback://embedded-snapshot',
+    };
+  }
+}
+
+function normalizeMetricValue(value, fallbackValue = 0) {
+  const parsedValue = Number(value);
+  if (!Number.isFinite(parsedValue)) {
+    return fallbackValue;
+  }
+
+  return clampNumericValue(parsedValue, 0, 1);
+}
+
+function calculateSnapshotSignalScore(snapshotSignalEntry) {
+  const metrics = snapshotSignalEntry?.metrics || {};
+  const ecosystemMaturity = normalizeMetricValue(metrics.ecosystemMaturity, 0.65);
+  const talentAvailability = normalizeMetricValue(metrics.talentAvailability, 0.65);
+  const deliveryVelocity = normalizeMetricValue(metrics.deliveryVelocity, 0.65);
+  const aggregateScore = (ecosystemMaturity + talentAvailability + deliveryVelocity) / 3;
+
+  return {
+    aggregateScore,
+    metrics: {
+      ecosystemMaturity,
+      talentAvailability,
+      deliveryVelocity,
+    },
+  };
+}
+
+function parseRealtimeSignalPayloadFromJson(rawJsonContent) {
+  try {
+    const parsedPayload = JSON.parse(rawJsonContent);
+    if (!Array.isArray(parsedPayload?.stackSignals)) {
+      return null;
+    }
+
+    return parsedPayload;
+  } catch {
+    return null;
+  }
+}
+
+function loadRealtimeSignalPayload(realtimeSignalFilePath) {
+  const normalizedRealtimeSignalFilePath = String(realtimeSignalFilePath || '').trim();
+  if (normalizedRealtimeSignalFilePath) {
+    try {
+      const absoluteRealtimeSignalPath = path.resolve(normalizedRealtimeSignalFilePath);
+      if (existsSync(absoluteRealtimeSignalPath)) {
+        const filePayload = parseRealtimeSignalPayloadFromJson(readFileSync(absoluteRealtimeSignalPath, 'utf8'));
+        if (filePayload) {
+          return {
+            payload: filePayload,
+            sourcePath: absoluteRealtimeSignalPath,
+          };
+        }
+      }
+    } catch {
+      // Ignore file loading errors and continue to environment fallback.
+    }
+  }
+
+  const signalPathFromEnvironment = String(process.env[ARCHITECT_DEFAULT_REALTIME_SIGNAL_PATH_ENV_KEY] || '').trim();
+  if (signalPathFromEnvironment) {
+    try {
+      const absoluteRealtimeSignalPath = path.resolve(signalPathFromEnvironment);
+      if (existsSync(absoluteRealtimeSignalPath)) {
+        const filePayload = parseRealtimeSignalPayloadFromJson(readFileSync(absoluteRealtimeSignalPath, 'utf8'));
+        if (filePayload) {
+          return {
+            payload: filePayload,
+            sourcePath: absoluteRealtimeSignalPath,
+          };
+        }
+      }
+    } catch {
+      // Ignore file loading errors and continue to environment JSON fallback.
+    }
+  }
+
+  const signalJsonFromEnvironment = String(process.env[ARCHITECT_DEFAULT_REALTIME_SIGNAL_ENV_KEY] || '').trim();
+  if (signalJsonFromEnvironment) {
+    const payloadFromEnvironment = parseRealtimeSignalPayloadFromJson(signalJsonFromEnvironment);
+    if (payloadFromEnvironment) {
+      return {
+        payload: payloadFromEnvironment,
+        sourcePath: `env://${ARCHITECT_DEFAULT_REALTIME_SIGNAL_ENV_KEY}`,
+      };
+    }
+  }
+
+  return {
+    payload: null,
+    sourcePath: null,
+  };
+}
+
+function normalizeStackSignalBoost(value) {
+  const normalizedSignal = normalizeMetricValue(value, 0);
+  return Number((normalizedSignal * 0.35).toFixed(4));
+}
+
+function normalizePaletteRoles(rawPaletteRoles) {
+  if (!Array.isArray(rawPaletteRoles) || rawPaletteRoles.length === 0) {
+    return ['base', 'surface', 'accent'];
+  }
+
+  const sanitizedRoles = rawPaletteRoles
+    .map((paletteRole) => String(paletteRole || '').trim().toLowerCase())
+    .filter((paletteRole) => ARCHITECT_ALLOWED_PALETTE_ROLES.includes(paletteRole));
+
+  if (sanitizedRoles.length === 0) {
+    return ['base', 'surface', 'accent'];
+  }
+
+  return Array.from(new Set(sanitizedRoles));
+}
+
+function normalizeTypographyScale(rawTypographyScale) {
+  const normalizedScale = String(rawTypographyScale || '').trim().toLowerCase();
+  if (ARCHITECT_ALLOWED_TYPOGRAPHY_SCALES.includes(normalizedScale)) {
+    return normalizedScale;
+  }
+
+  return 'balanced';
+}
+
+function normalizeSpacingPattern(rawSpacingPattern) {
+  const normalizedPattern = String(rawSpacingPattern || '').trim().toLowerCase();
+  if (ARCHITECT_ALLOWED_SPACING_PATTERNS.includes(normalizedPattern)) {
+    return normalizedPattern;
+  }
+
+  return 'balanced-grid';
+}
+
+function normalizeMotionCharacteristics(rawMotionCharacteristics) {
+  if (!Array.isArray(rawMotionCharacteristics) || rawMotionCharacteristics.length === 0) {
+    return ['subtle-enter', 'state-feedback'];
+  }
+
+  const sanitizedCharacteristics = rawMotionCharacteristics
+    .map((motionCharacteristic) => String(motionCharacteristic || '').trim().toLowerCase())
+    .filter((motionCharacteristic) => ARCHITECT_ALLOWED_MOTION_CHARACTERISTICS.includes(motionCharacteristic));
+
+  if (sanitizedCharacteristics.length === 0) {
+    return ['subtle-enter', 'state-feedback'];
+  }
+
+  return Array.from(new Set(sanitizedCharacteristics));
+}
+
+function synthesizeDesignSignals({
+  normalizedProjectDescription,
+  recommendedStackFileName,
+  realtimePayload,
+  snapshotGeneratedAt,
+}) {
+  const descriptionText = String(normalizedProjectDescription || '');
+  const looksLikeFinancialSurface = /fraud|bank|payment|regulated|security/.test(descriptionText);
+  const looksLikeGrowthSurface = /marketing|landing|conversion|sales|campaign/.test(descriptionText);
+  const looksLikeDataProduct = /analytics|dashboard|report|insight|data/.test(descriptionText);
+
+  let paletteRoles = ['base', 'surface', 'accent'];
+  let typographyScale = 'balanced';
+  let spacingPattern = 'balanced-grid';
+  let motionCharacteristics = ['subtle-enter', 'state-feedback'];
+
+  if (looksLikeFinancialSurface) {
+    paletteRoles = ['base', 'surface', 'accent', 'danger', 'success'];
+    motionCharacteristics = ['calm-transition', 'state-feedback'];
+  } else if (looksLikeGrowthSurface) {
+    paletteRoles = ['base', 'surface', 'accent', 'success'];
+    typographyScale = 'expressive';
+    motionCharacteristics = ['staggered-reveal', 'conversion-focus', 'state-feedback'];
+  }
+
+  if (looksLikeDataProduct || recommendedStackFileName === 'python.md') {
+    spacingPattern = 'compact-grid';
+  }
+
+  const realtimeDesignSignals = realtimePayload?.designSignals || null;
+  if (realtimeDesignSignals) {
+    paletteRoles = normalizePaletteRoles(realtimeDesignSignals.paletteRoles || paletteRoles);
+    typographyScale = normalizeTypographyScale(realtimeDesignSignals.typographyScale || typographyScale);
+    spacingPattern = normalizeSpacingPattern(realtimeDesignSignals.spacingPattern || spacingPattern);
+    motionCharacteristics = normalizeMotionCharacteristics(
+      realtimeDesignSignals.motionCharacteristics || motionCharacteristics
+    );
+  }
+
+  return {
+    generatedAt: snapshotGeneratedAt,
+    normalizedSignals: {
+      paletteRoles,
+      typographyScale,
+      spacingPattern,
+      motionCharacteristics,
+    },
+    sourcePolicy: {
+      normalizedSignalsOnly: true,
+      copiedExternalProse: false,
+      blockedInputPacks: ['DESIGN.md'],
+    },
+  };
+}
+
+function buildEvidenceCitation({
+  citationId,
+  sourceType,
+  sourceName,
+  sourceUrl,
+  measuredAt,
+  stackFileName,
+  metrics,
+  note,
+}) {
+  return {
+    citationId,
+    sourceType,
+    sourceName,
+    sourceUrl,
+    measuredAt: toIsoTimestamp(measuredAt),
+    stackFileName,
+    metrics,
+    note,
+  };
+}
+
 function buildFallbackRecommendation({
   stackFileNames,
   blueprintFileNames,
@@ -148,14 +519,45 @@ function buildFallbackRecommendation({
   usedTokens,
   elapsedMs,
   timeoutTriggered,
+  requestedResearchMode,
+  effectiveResearchMode,
+  snapshot,
+  snapshotSourcePath,
+  realtimeGateEnabled,
+  realtimeSignalsLoaded,
+  realtimeSignalSourcePath,
+  normalizedProjectDescription,
 }) {
   const fallbackStackFileName = stackFileNames.includes('typescript.md')
     ? 'typescript.md'
     : stackFileNames[0] || 'typescript.md';
   const fallbackBlueprintFileName = resolveRecommendedBlueprintFileName(fallbackStackFileName, blueprintFileNames);
+  const fallbackSnapshotSignal = Array.isArray(snapshot?.stackSignals)
+    ? snapshot.stackSignals.find((stackSignal) => stackSignal.stackFileName === fallbackStackFileName) || null
+    : null;
+  const fallbackSnapshotMetrics = calculateSnapshotSignalScore(fallbackSnapshotSignal);
+  const fallbackEvidenceCitations = [
+    buildEvidenceCitation({
+      citationId: `snapshot:${snapshot?.snapshotId || 'fallback'}:${fallbackStackFileName}`,
+      sourceType: 'snapshot',
+      sourceName: snapshot?.sourceName || 'Stack research snapshot',
+      sourceUrl: snapshot?.sourceUrl || snapshotSourcePath,
+      measuredAt: fallbackSnapshotSignal?.measuredAt || snapshot?.generatedAt,
+      stackFileName: fallbackStackFileName,
+      metrics: fallbackSnapshotMetrics.metrics,
+      note: 'Deterministic snapshot baseline used for fallback recommendation.',
+    }),
+  ];
+
+  const fallbackDesignGuidance = synthesizeDesignSignals({
+    normalizedProjectDescription,
+    recommendedStackFileName: fallbackStackFileName,
+    realtimePayload: null,
+    snapshotGeneratedAt: toIsoTimestamp(snapshot?.generatedAt),
+  });
 
   return {
-    projectDescription: '',
+    projectDescription: String(normalizedProjectDescription || '').trim(),
     recommendedStackFileName: fallbackStackFileName,
     recommendedBlueprintFileName: fallbackBlueprintFileName,
     confidenceLabel: 'low',
@@ -176,7 +578,25 @@ function buildFallbackRecommendation({
       lowConfidence: true,
       dataConflict: false,
       repeatedOverride: false,
+      realtimeGated: requestedResearchMode === 'realtime' && !realtimeGateEnabled,
+      realtimeUnavailable: requestedResearchMode === 'realtime' && realtimeGateEnabled && !realtimeSignalsLoaded,
+    },
+    research: {
+      requestedMode: requestedResearchMode,
+      effectiveMode: effectiveResearchMode,
+      deterministic: effectiveResearchMode === 'snapshot',
+      snapshotId: snapshot?.snapshotId || 'fallback',
+      snapshotGeneratedAt: toIsoTimestamp(snapshot?.generatedAt),
+      snapshotSourcePath,
+      realtimeGateEnabled,
+      realtimeSignalsLoaded,
+      realtimeSignalSourcePath,
+      trustedRealtimeSources: Array.isArray(snapshot?.trustedRealtimeSources)
+        ? snapshot.trustedRealtimeSources
+        : [],
     },
+    evidenceCitations: fallbackEvidenceCitations,
+    designGuidance: fallbackDesignGuidance,
     researchBudget: {
       tokenBudget,
       timeoutMs,
@@ -195,16 +615,40 @@ export function recommendArchitecture({
   blueprintFileNames,
   tokenBudget = ARCHITECT_DEFAULT_TOKEN_BUDGET,
   timeoutMs = ARCHITECT_DEFAULT_TIMEOUT_MS,
+  researchMode = ARCHITECT_DEFAULT_RESEARCH_MODE,
+  enableRealtimeResearch = false,
+  realtimeSignalFilePath = null,
 }) {
   const startedAt = Date.now();
   const boundedTokenBudget = clampNumericValue(tokenBudget, ARCHITECT_MIN_TOKEN_BUDGET, ARCHITECT_MAX_TOKEN_BUDGET);
   const boundedTimeoutMs = clampNumericValue(timeoutMs, ARCHITECT_MIN_TIMEOUT_MS, ARCHITECT_MAX_TIMEOUT_MS);
+  const requestedResearchMode = normalizeArchitectResearchMode(researchMode);
+  const { snapshot: stackResearchSnapshot, sourcePath: snapshotSourcePath } = loadStackResearchSnapshot();
+  const snapshotGeneratedAt = toIsoTimestamp(stackResearchSnapshot.generatedAt);
+  const realtimeGateEnabled = requestedResearchMode === 'realtime' && enableRealtimeResearch === true;
+  const realtimeSignalPayloadResult = realtimeGateEnabled
+    ? loadRealtimeSignalPayload(realtimeSignalFilePath)
+    : { payload: null, sourcePath: null };
+  const realtimeSignalPayload = realtimeSignalPayloadResult.payload;
+  const realtimeSignalsLoaded = Array.isArray(realtimeSignalPayload?.stackSignals)
+    && realtimeSignalPayload.stackSignals.length > 0;
+  const effectiveResearchMode = realtimeGateEnabled && realtimeSignalsLoaded
+    ? 'realtime'
+    : 'snapshot';
   const normalizedDescription = String(projectDescription || '').trim().toLowerCase();
   const effectiveDescriptionSeed = normalizedDescription || 'general software project';
   let effectiveDescription = effectiveDescriptionSeed;
   let usedTokens = estimateTokenUsage(effectiveDescription) + 120;
   const uncertaintyNotes = [];
 
+  if (requestedResearchMode === 'realtime' && !realtimeGateEnabled) {
+    uncertaintyNotes.push('Realtime research mode requested but gate is off. Using deterministic snapshot baseline.');
+  }
+
+  if (requestedResearchMode === 'realtime' && realtimeGateEnabled && !realtimeSignalsLoaded) {
+    uncertaintyNotes.push('Realtime research gate is on, but no trusted realtime payload was available. Using deterministic snapshot baseline.');
+  }
+
   if (usedTokens > boundedTokenBudget) {
     effectiveDescription = effectiveDescription.slice(0, Math.max(120, boundedTokenBudget * 4));
     usedTokens = boundedTokenBudget;
@@ -220,9 +664,51 @@ export function recommendArchitecture({
       usedTokens,
       elapsedMs: Date.now() - startedAt,
       timeoutTriggered: true,
+      requestedResearchMode,
+      effectiveResearchMode,
+      snapshot: stackResearchSnapshot,
+      snapshotSourcePath,
+      realtimeGateEnabled,
+      realtimeSignalsLoaded,
+      realtimeSignalSourcePath: realtimeSignalPayloadResult.sourcePath,
+      normalizedProjectDescription: normalizedDescription,
     });
   }
 
+  const snapshotSignalByStackFileName = new Map();
+  for (const snapshotSignalEntry of stackResearchSnapshot?.stackSignals || []) {
+    if (!snapshotSignalEntry?.stackFileName) {
+      continue;
+    }
+
+    snapshotSignalByStackFileName.set(snapshotSignalEntry.stackFileName, snapshotSignalEntry);
+  }
+
+  const realtimeSignalByStackFileName = new Map();
+  if (realtimeSignalsLoaded) {
+    for (const realtimeSignalEntry of realtimeSignalPayload.stackSignals) {
+      const stackFileName = realtimeSignalEntry?.stackFileName;
+      if (!stackFileName || !stackFileNames.includes(stackFileName)) {
+        continue;
+      }
+
+      const rawRealtimeSignalStrength = realtimeSignalEntry.signalStrength
+        ?? realtimeSignalEntry.metrics?.signalStrength
+        ?? 0;
+      const normalizedRealtimeSignalStrength = normalizeMetricValue(rawRealtimeSignalStrength, 0);
+      realtimeSignalByStackFileName.set(stackFileName, {
+        signalBoost: normalizeStackSignalBoost(normalizedRealtimeSignalStrength),
+        measuredAt: realtimeSignalEntry.measuredAt || realtimeSignalPayload.generatedAt || snapshotGeneratedAt,
+        sourceName: realtimeSignalEntry.sourceName || realtimeSignalPayload.sourceName || 'Trusted realtime source',
+        sourceUrl: realtimeSignalEntry.sourceUrl || realtimeSignalPayload.sourceUrl || realtimeSignalPayloadResult.sourcePath,
+        metrics: {
+          signalStrength: normalizedRealtimeSignalStrength,
+          freshnessHours: Number(realtimeSignalEntry.metrics?.freshnessHours) || 0,
+        },
+      });
+    }
+  }
+
   const detectionScoreByStackFileName = new Map();
   for (const rankedCandidate of projectDetection?.rankedCandidates || []) {
     const confidenceScore = Number(rankedCandidate.confidenceScore) || 0;
@@ -251,13 +737,26 @@ export function recommendArchitecture({
     }
 
     const detectionSignalScore = detectionScoreByStackFileName.get(stackFileName) || 0;
-    const totalScore = 0.2 + keywordSignalScore + detectionSignalScore;
+    const snapshotSignalEntry = snapshotSignalByStackFileName.get(stackFileName) || null;
+    const snapshotSignalScorePayload = calculateSnapshotSignalScore(snapshotSignalEntry);
+    const snapshotSignalScore = normalizeStackSignalBoost(snapshotSignalScorePayload.aggregateScore);
+    const realtimeSignalPayloadEntry = realtimeSignalByStackFileName.get(stackFileName) || null;
+    const realtimeSignalScore = realtimeSignalPayloadEntry?.signalBoost || 0;
+    const totalScore = 0.2 + keywordSignalScore + detectionSignalScore + snapshotSignalScore + realtimeSignalScore;
 
     return {
       stackFileName,
       totalScore,
       keywordSignalScore,
       detectionSignalScore,
+      snapshotSignalScore,
+      snapshotMetrics: snapshotSignalScorePayload.metrics,
+      realtimeSignalScore,
+      realtimeMetrics: realtimeSignalPayloadEntry?.metrics || null,
+      snapshotMeasuredAt: snapshotSignalEntry?.measuredAt || stackResearchSnapshot.generatedAt,
+      realtimeMeasuredAt: realtimeSignalPayloadEntry?.measuredAt || null,
+      realtimeSourceName: realtimeSignalPayloadEntry?.sourceName || null,
+      realtimeSourceUrl: realtimeSignalPayloadEntry?.sourceUrl || null,
       matchedSignals,
     };
   }).sort((leftCandidate, rightCandidate) => rightCandidate.totalScore - leftCandidate.totalScore);
@@ -271,6 +770,14 @@ export function recommendArchitecture({
       usedTokens,
       elapsedMs: Date.now() - startedAt,
       timeoutTriggered: false,
+      requestedResearchMode,
+      effectiveResearchMode,
+      snapshot: stackResearchSnapshot,
+      snapshotSourcePath,
+      realtimeGateEnabled,
+      realtimeSignalsLoaded,
+      realtimeSignalSourcePath: realtimeSignalPayloadResult.sourcePath,
+      normalizedProjectDescription: normalizedDescription,
     });
   }
 
@@ -308,9 +815,15 @@ export function recommendArchitecture({
 
   const recommendedStackFileName = strongestCandidate.stackFileName;
   const recommendedBlueprintFileName = resolveRecommendedBlueprintFileName(recommendedStackFileName, blueprintFileNames);
-  const signalSummary = strongestCandidate.matchedSignals.length > 0
-    ? strongestCandidate.matchedSignals.slice(0, 4).join(', ')
-    : 'limited direct stack keywords';
+  const signalSummaryParts = [];
+  if (strongestCandidate.matchedSignals.length > 0) {
+    signalSummaryParts.push(strongestCandidate.matchedSignals.slice(0, 4).join(', '));
+  }
+  signalSummaryParts.push(`snapshot ${strongestCandidate.snapshotSignalScore.toFixed(2)}`);
+  if (strongestCandidate.realtimeSignalScore > 0) {
+    signalSummaryParts.push(`realtime ${strongestCandidate.realtimeSignalScore.toFixed(2)}`);
+  }
+  const signalSummary = signalSummaryParts.join(', ');
 
   const rationaleSentences = [
     `I recommend ${toTitleCase(recommendedStackFileName)} with ${toTitleCase(recommendedBlueprintFileName)} for this project.`,
@@ -322,6 +835,92 @@ export function recommendArchitecture({
     rationaleSentences.push('Confidence is low, so review alternatives before finalizing architecture.');
   }
 
+  const evidenceCitations = [
+    buildEvidenceCitation({
+      citationId: `snapshot:${stackResearchSnapshot.snapshotId || 'snapshot'}:${recommendedStackFileName}`,
+      sourceType: 'snapshot',
+      sourceName: stackResearchSnapshot.sourceName || 'Stack research snapshot',
+      sourceUrl: stackResearchSnapshot.sourceUrl || snapshotSourcePath,
+      measuredAt: strongestCandidate.snapshotMeasuredAt || snapshotGeneratedAt,
+      stackFileName: recommendedStackFileName,
+      metrics: strongestCandidate.snapshotMetrics,
+      note: 'Deterministic stack research snapshot signal.',
+    }),
+  ];
+
+  if (projectDetection?.recommendedStackFileName) {
+    evidenceCitations.push(
+      buildEvidenceCitation({
+        citationId: `detector:${projectDetection.recommendedStackFileName}`,
+        sourceType: 'detection',
+        sourceName: 'Existing project marker detector',
+        sourceUrl: 'state://project-detection',
+        measuredAt: snapshotGeneratedAt,
+        stackFileName: projectDetection.recommendedStackFileName,
+        metrics: {
+          confidenceScore: Number(projectDetection.confidenceScore || 0),
+          confidenceGap: Number(projectDetection.confidenceGap || 0),
+        },
+        note: 'Repository marker detection signal used for stack recommendation bias.',
+      })
+    );
+  }
+
+  if (effectiveResearchMode === 'realtime') {
+    const realtimeCitationCandidate = strongestCandidate.realtimeSignalScore > 0
+      ? strongestCandidate
+      : scoredStackCandidates.find((stackCandidate) => stackCandidate.realtimeSignalScore > 0) || null;
+
+    if (realtimeCitationCandidate) {
+      const realtimeCitationOnRecommendedStack = realtimeCitationCandidate.stackFileName === recommendedStackFileName;
+      evidenceCitations.push(
+        buildEvidenceCitation({
+          citationId: `realtime:${realtimeCitationCandidate.stackFileName}`,
+          sourceType: 'realtime',
+          sourceName: realtimeCitationCandidate.realtimeSourceName || 'Trusted realtime source',
+          sourceUrl: realtimeCitationCandidate.realtimeSourceUrl || realtimeSignalPayloadResult.sourcePath,
+          measuredAt: realtimeCitationCandidate.realtimeMeasuredAt || snapshotGeneratedAt,
+          stackFileName: realtimeCitationCandidate.stackFileName,
+          metrics: realtimeCitationCandidate.realtimeMetrics
+            || { signalStrength: realtimeCitationCandidate.realtimeSignalScore },
+          note: realtimeCitationOnRecommendedStack
+            ? 'Optional realtime signal, loaded only when realtime research is explicitly gated on.'
+            : 'Optional realtime signal loaded for an alternative stack signal; used as supporting evidence in realtime mode.',
+        })
+      );
+    } else if (realtimeSignalsLoaded && Array.isArray(realtimeSignalPayload?.stackSignals) && realtimeSignalPayload.stackSignals.length > 0) {
+      const fallbackRealtimeSignal = realtimeSignalPayload.stackSignals[0];
+      const fallbackRealtimeSignalStrength = normalizeMetricValue(
+        fallbackRealtimeSignal?.signalStrength
+          ?? fallbackRealtimeSignal?.metrics?.signalStrength
+          ?? 0,
+        0
+      );
+
+      evidenceCitations.push(
+        buildEvidenceCitation({
+          citationId: 'realtime:payload-fallback',
+          sourceType: 'realtime',
+          sourceName: fallbackRealtimeSignal?.sourceName || realtimeSignalPayload.sourceName || 'Trusted realtime source',
+          sourceUrl: fallbackRealtimeSignal?.sourceUrl || realtimeSignalPayload.sourceUrl || realtimeSignalPayloadResult.sourcePath,
+          measuredAt: fallbackRealtimeSignal?.measuredAt || realtimeSignalPayload.generatedAt || snapshotGeneratedAt,
+          stackFileName: recommendedStackFileName,
+          metrics: {
+            signalStrength: fallbackRealtimeSignalStrength,
+          },
+          note: 'Optional realtime payload loaded, but stack mapping did not match current candidate set. Stored as trace citation.',
+        })
+      );
+    }
+  }
+
+  const designGuidance = synthesizeDesignSignals({
+    normalizedProjectDescription: normalizedDescription,
+    recommendedStackFileName,
+    realtimePayload: effectiveResearchMode === 'realtime' ? realtimeSignalPayload : null,
+    snapshotGeneratedAt,
+  });
+
   const alternatives = scoredStackCandidates
     .slice(1, 3)
     .map((stackCandidate) => {
@@ -331,6 +930,7 @@ export function recommendArchitecture({
         blueprintFileName: alternativeBlueprintFileName,
         oneLineTradeoff: STACK_TRADEOFF_SUMMARIES[stackCandidate.stackFileName]
           || 'validate fit with your runtime and team constraints.',
+        evidenceSummary: `keyword=${stackCandidate.keywordSignalScore.toFixed(2)}, detection=${stackCandidate.detectionSignalScore.toFixed(2)}, snapshot=${stackCandidate.snapshotSignalScore.toFixed(2)}, realtime=${stackCandidate.realtimeSignalScore.toFixed(2)}`,
       };
     });
 
@@ -344,6 +944,14 @@ export function recommendArchitecture({
       usedTokens,
       elapsedMs,
       timeoutTriggered: true,
+      requestedResearchMode,
+      effectiveResearchMode,
+      snapshot: stackResearchSnapshot,
+      snapshotSourcePath,
+      realtimeGateEnabled,
+      realtimeSignalsLoaded,
+      realtimeSignalSourcePath: realtimeSignalPayloadResult.sourcePath,
+      normalizedProjectDescription: normalizedDescription,
     });
   }
 
@@ -361,7 +969,25 @@ export function recommendArchitecture({
       lowConfidence,
       dataConflict,
       repeatedOverride: false,
+      realtimeGated: requestedResearchMode === 'realtime' && !realtimeGateEnabled,
+      realtimeUnavailable: requestedResearchMode === 'realtime' && realtimeGateEnabled && !realtimeSignalsLoaded,
     },
+    research: {
+      requestedMode: requestedResearchMode,
+      effectiveMode: effectiveResearchMode,
+      deterministic: effectiveResearchMode === 'snapshot',
+      snapshotId: stackResearchSnapshot.snapshotId || 'snapshot',
+      snapshotGeneratedAt,
+      snapshotSourcePath,
+      realtimeGateEnabled,
+      realtimeSignalsLoaded,
+      realtimeSignalSourcePath: realtimeSignalPayloadResult.sourcePath,
+      trustedRealtimeSources: Array.isArray(stackResearchSnapshot.trustedRealtimeSources)
+        ? stackResearchSnapshot.trustedRealtimeSources
+        : [],
+    },
+    evidenceCitations,
+    designGuidance,
     researchBudget: {
       tokenBudget: boundedTokenBudget,
       timeoutMs: boundedTimeoutMs,
@@ -374,11 +1000,15 @@ export function recommendArchitecture({
 }
 
 export function formatArchitectureRecommendation(architectureRecommendation) {
+  const researchModeSummary = architectureRecommendation.research
+    ? `${architectureRecommendation.research.requestedMode} -> ${architectureRecommendation.research.effectiveMode}`
+    : 'snapshot';
   const outputLines = [
     '\nArchitecture recommendation (project-description-first):',
     `- Stack: ${toTitleCase(architectureRecommendation.recommendedStackFileName)}`,
     `- Blueprint: ${toTitleCase(architectureRecommendation.recommendedBlueprintFileName)}`,
     `- Confidence: ${architectureRecommendation.confidenceLabel} (${architectureRecommendation.confidenceScore})`,
+    `- Research mode: ${researchModeSummary}`,
     '- Rationale:',
     ...architectureRecommendation.rationaleSentences.map((sentence, sentenceIndex) => `  ${sentenceIndex + 1}. ${sentence}`),
     '- Alternatives:',
@@ -418,6 +1048,27 @@ export function formatArchitectureRecommendation(architectureRecommendation) {
     outputLines.push(`- Caution labels: ${cautionLabels.join(', ')}`);
   }
 
+  if (Array.isArray(architectureRecommendation.evidenceCitations) && architectureRecommendation.evidenceCitations.length > 0) {
+    outputLines.push('- Evidence citations (measurable source + timestamp):');
+    outputLines.push(
+      ...architectureRecommendation.evidenceCitations.map((citationEntry, citationIndex) => {
+        const metricsSummary = Object.entries(citationEntry.metrics || {})
+          .map(([metricKey, metricValue]) => `${metricKey}=${metricValue}`)
+          .join(', ');
+        return `  ${citationIndex + 1}. [${citationEntry.sourceType}] ${citationEntry.sourceName} @ ${citationEntry.measuredAt} (${metricsSummary || 'no metrics'})`;
+      })
+    );
+  }
+
+  if (architectureRecommendation.designGuidance?.normalizedSignals) {
+    const normalizedSignals = architectureRecommendation.designGuidance.normalizedSignals;
+    outputLines.push('- Design signal synthesis (normalized, no copied external prose):');
+    outputLines.push(`  1. Palette roles: ${normalizedSignals.paletteRoles.join(', ')}`);
+    outputLines.push(`  2. Typography scale: ${normalizedSignals.typographyScale}`);
+    outputLines.push(`  3. Spacing pattern: ${normalizedSignals.spacingPattern}`);
+    outputLines.push(`  4. Motion characteristics: ${normalizedSignals.motionCharacteristics.join(', ')}`);
+  }
+
   outputLines.push(
     `- Research guardrails: ${architectureRecommendation.researchBudget.usedTokens}/${architectureRecommendation.researchBudget.tokenBudget} tokens, ${architectureRecommendation.researchBudget.elapsedMs}ms/${architectureRecommendation.researchBudget.timeoutMs}ms`
   );

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;
 }
@@ -843,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 = {

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.19",
+  "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

@@ -180,6 +180,29 @@ const REQUIRED_DETECTION_TRANSPARENCY_SNIPPETS = [
     ],
   },
 ];
+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,
@@ -300,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',
@@ -975,6 +999,93 @@ async function validateDetectionTransparencyCoverage() {
   }
 }
 
+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...');
 
@@ -1225,6 +1336,8 @@ async function main() {
   await validateDocumentationFlow();
   await validateTerminologyMapping();
   await validateDetectionTransparencyCoverage();
+  await validateStackResearchEngineCoverage();
+  await validateStackResearchSnapshotState();
   await validateMcpConfiguration();
   await validateHumanWritingGovernance();
   await validateInstructionAdapters();