@ryuenn3123/agentic-senior-core 2.5.8 → 2.5.10

package/.agent-context/review-checklists/frontend-excellence-rubric.md

@@ -43,6 +43,15 @@ Release recommendation:
 - [ ] Error, empty, and loading states provide clear next actions.
 - [ ] User journey avoids dead ends and hidden critical actions.
 
+## 7. Template Diversity and Originality
+- [ ] Output is not a copy of a generic starter template or repeated AI layout pattern.
+- [ ] Layout composition shows intentional variation in structure and hierarchy.
+- [ ] Visual intent, interaction quality, and conversion clarity are all explicitly reviewed together.
+
+## Low-Diversity Template Output Policy
+- If output is judged as low-diversity template output, release is blocked until layout direction is revised.
+- Reviewer must record the failing dimensions and expected redesign direction before re-run.
+
 ## Benchmark Expectation
 - Treat MiniMax frontend references as baseline, not target ceiling.
 - Target visual and interaction quality aligned with top award-grade manual design workflows (Awwwards-level reference quality).

package/.agent-context/rules/frontend-architecture.md

@@ -2,6 +2,20 @@
 
 > A complex UI is built from simple, mathematically robust functions. State is dangerous; isolate it.
 
+## 0. Frontend Designer Mode (Auto Activation)
+When the user request is UI-facing, frontend design governance activates automatically. No manual mode toggle is required.
+
+UI scope trigger signals (any one is enough):
+- keywords such as: ui, ux, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction
+- explicit requests to improve visual quality, conversion clarity, or interaction behavior
+- feature requests that include frontend deliverables even when backend changes are also included
+
+Mandatory behavior when triggered:
+- apply frontend excellence rubric checks from `.agent-context/review-checklists/frontend-excellence-rubric.md`
+- apply usability checks from `.agent-context/review-checklists/frontend-usability.md`
+- score and review generated UI work against visual intent, interaction quality, and conversion clarity
+- reject template-only repetitive outputs and force a distinct layout direction
+
 ## 1. File Structure (Feature-Driven Design)
 Organize your application by feature domain, not by file type.
 - **BANNED:** Monolithic directories like `/components` (with 500 files), `/hooks`, `/api`.

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

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-17T07:42:53.417Z",
+  "generatedAt": "2026-04-17T08:10:30.670Z",
   "reportName": "memory-continuity-benchmark",
   "schemaVersion": "1.0.0",
   "passed": true,

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.5.8
+Generated by Agentic-Senior-Core CLI v2.5.10
 Timestamp: 2026-04-15T00:14:51.184Z
 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.8
+Generated by Agentic-Senior-Core CLI v2.5.10
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/README.md

@@ -30,6 +30,12 @@ Optional team default path:
 npx @ryuenn3123/agentic-senior-core init --profile-pack startup
 ```
 
+Project-description-first path (AI as Architect with veto control):
+
+```bash
+npx @ryuenn3123/agentic-senior-core init --project-description "Machine learning API for fraud detection"
+```
+
 ---
 
 ## Before / After

package/lib/cli/architect.mjs

@@ -0,0 +1,493 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { BLUEPRINT_RECOMMENDATIONS } from './constants.mjs';
+import { ensureDirectory, pathExists, toTitleCase } from './utils.mjs';
+
+export const ARCHITECT_DEFAULT_TOKEN_BUDGET = 900;
+export const ARCHITECT_DEFAULT_TIMEOUT_MS = 1500;
+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;
+
+const ARCHITECT_PREFERENCE_FILE_PATH = process.env.AGENTIC_ARCHITECT_PREF_FILE
+  ? path.resolve(process.env.AGENTIC_ARCHITECT_PREF_FILE)
+  : path.join(os.homedir(), '.agentic-senior-core', 'architect-preferences.json');
+
+const STACK_SIGNAL_WEIGHTS = {
+  'typescript.md': [
+    { term: 'typescript', weight: 0.9 },
+    { term: 'javascript', weight: 0.8 },
+    { term: 'node', weight: 0.55 },
+    { term: 'next.js', weight: 0.7 },
+    { term: 'nextjs', weight: 0.7 },
+    { term: 'react', weight: 0.45 },
+    { term: 'web app', weight: 0.45 },
+    { term: 'frontend', weight: 0.4 },
+    { term: 'dashboard', weight: 0.35 },
+  ],
+  'python.md': [
+    { term: 'python', weight: 0.95 },
+    { term: 'fastapi', weight: 0.8 },
+    { term: 'machine learning', weight: 0.8 },
+    { term: 'ml', weight: 0.4 },
+    { term: 'data', weight: 0.45 },
+    { term: 'ai', weight: 0.45 },
+    { term: 'automation', weight: 0.35 },
+    { term: 'analytics', weight: 0.35 },
+  ],
+  'java.md': [
+    { term: 'java', weight: 0.9 },
+    { term: 'spring', weight: 0.75 },
+    { term: 'enterprise', weight: 0.45 },
+    { term: 'bank', weight: 0.35 },
+    { term: 'regulated', weight: 0.35 },
+    { term: 'jvm', weight: 0.35 },
+  ],
+  'php.md': [
+    { term: 'php', weight: 0.9 },
+    { term: 'laravel', weight: 0.8 },
+    { term: 'cms', weight: 0.4 },
+    { term: 'wordpress', weight: 0.35 },
+  ],
+  'go.md': [
+    { term: 'go', weight: 0.5 },
+    { term: 'golang', weight: 0.9 },
+    { term: 'high throughput', weight: 0.55 },
+    { term: 'microservice', weight: 0.45 },
+    { term: 'kubernetes', weight: 0.45 },
+    { term: 'latency', weight: 0.35 },
+    { term: 'concurrency', weight: 0.35 },
+  ],
+  'csharp.md': [
+    { term: '.net', weight: 0.9 },
+    { term: 'dotnet', weight: 0.9 },
+    { term: 'c#', weight: 0.75 },
+    { term: 'asp.net', weight: 0.8 },
+    { term: 'microsoft', weight: 0.35 },
+  ],
+  'rust.md': [
+    { term: 'rust', weight: 0.9 },
+    { term: 'systems', weight: 0.45 },
+    { term: 'performance', weight: 0.35 },
+    { term: 'memory safety', weight: 0.4 },
+    { term: 'low latency', weight: 0.4 },
+  ],
+  'ruby.md': [
+    { term: 'ruby', weight: 0.9 },
+    { term: 'rails', weight: 0.8 },
+    { term: 'monolith', weight: 0.35 },
+    { term: 'crud', weight: 0.3 },
+  ],
+  'react-native.md': [
+    { term: 'react native', weight: 0.9 },
+    { term: 'mobile', weight: 0.4 },
+    { term: 'android', weight: 0.35 },
+    { term: 'ios', weight: 0.35 },
+    { term: 'cross-platform', weight: 0.4 },
+  ],
+  'flutter.md': [
+    { term: 'flutter', weight: 0.95 },
+    { term: 'dart', weight: 0.8 },
+    { term: 'mobile', weight: 0.4 },
+    { term: 'android', weight: 0.35 },
+    { term: 'ios', weight: 0.35 },
+    { term: 'cross-platform', weight: 0.4 },
+  ],
+};
+
+const STACK_TRADEOFF_SUMMARIES = {
+  'typescript.md': 'great fullstack velocity, but dependency churn and runtime startup need discipline.',
+  'python.md': 'fast AI and API delivery, but strict latency targets may need extra optimization.',
+  'java.md': 'strong enterprise reliability, but setup and boilerplate are heavier.',
+  'php.md': 'rapid web product iteration, but architecture boundaries must be guarded early.',
+  'go.md': 'excellent throughput and operational simplicity, but abstractions are intentionally minimal.',
+  'csharp.md': 'strong for Microsoft-centered teams, but cross-platform tooling choices should be explicit.',
+  'rust.md': 'top performance and safety, but development ramp-up is steeper.',
+  'ruby.md': 'high productivity for product teams, but scaling strategy should be planned early.',
+  'react-native.md': 'single codebase for mobile, but native edge cases still require platform attention.',
+  'flutter.md': 'consistent UI across mobile platforms, but ecosystem fit should be checked per package.',
+};
+
+function clampNumericValue(value, minimumValue, maximumValue) {
+  return Math.min(Math.max(value, minimumValue), maximumValue);
+}
+
+function estimateTokenUsage(textValue) {
+  return Math.ceil(String(textValue || '').length / 4);
+}
+
+function resolveConfidenceLabel(confidenceScore) {
+  if (confidenceScore >= 0.85) {
+    return 'high';
+  }
+
+  if (confidenceScore >= 0.7) {
+    return 'medium';
+  }
+
+  return 'low';
+}
+
+function resolveRecommendedBlueprintFileName(stackFileName, blueprintFileNames) {
+  const recommendedBlueprintFileName = BLUEPRINT_RECOMMENDATIONS[stackFileName] || null;
+  if (recommendedBlueprintFileName && blueprintFileNames.includes(recommendedBlueprintFileName)) {
+    return recommendedBlueprintFileName;
+  }
+
+  return blueprintFileNames[0] || null;
+}
+
+function buildFallbackRecommendation({
+  stackFileNames,
+  blueprintFileNames,
+  tokenBudget,
+  timeoutMs,
+  usedTokens,
+  elapsedMs,
+  timeoutTriggered,
+}) {
+  const fallbackStackFileName = stackFileNames.includes('typescript.md')
+    ? 'typescript.md'
+    : stackFileNames[0] || 'typescript.md';
+  const fallbackBlueprintFileName = resolveRecommendedBlueprintFileName(fallbackStackFileName, blueprintFileNames);
+
+  return {
+    projectDescription: '',
+    recommendedStackFileName: fallbackStackFileName,
+    recommendedBlueprintFileName: fallbackBlueprintFileName,
+    confidenceLabel: 'low',
+    confidenceScore: 0.45,
+    rationaleSentences: [
+      `I recommend ${toTitleCase(fallbackStackFileName)} with ${toTitleCase(fallbackBlueprintFileName)} as a safe fallback path.`,
+      'The architecture recommendation budget was constrained before a stronger stack signal could be computed.',
+      `Main trade-off: ${STACK_TRADEOFF_SUMMARIES[fallbackStackFileName] || 'validate ecosystem fit before production rollout.'}`,
+    ],
+    alternatives: [],
+    uncertaintyNotes: [
+      timeoutTriggered
+        ? 'Timeout guardrail triggered before recommendation analysis completed.'
+        : 'Input signals were not strong enough for a high-confidence architecture recommendation.',
+    ],
+    signalSummary: 'fallback mode',
+    failureModes: {
+      lowConfidence: true,
+      dataConflict: false,
+      repeatedOverride: false,
+    },
+    researchBudget: {
+      tokenBudget,
+      timeoutMs,
+      usedTokens: Math.min(usedTokens, tokenBudget),
+      elapsedMs: Math.min(elapsedMs, timeoutMs),
+      tokenBudgetCapped: usedTokens >= tokenBudget,
+      timeoutTriggered,
+    },
+  };
+}
+
+export function recommendArchitecture({
+  projectDescription,
+  projectDetection,
+  stackFileNames,
+  blueprintFileNames,
+  tokenBudget = ARCHITECT_DEFAULT_TOKEN_BUDGET,
+  timeoutMs = ARCHITECT_DEFAULT_TIMEOUT_MS,
+}) {
+  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 normalizedDescription = String(projectDescription || '').trim().toLowerCase();
+  const effectiveDescriptionSeed = normalizedDescription || 'general software project';
+  let effectiveDescription = effectiveDescriptionSeed;
+  let usedTokens = estimateTokenUsage(effectiveDescription) + 120;
+  const uncertaintyNotes = [];
+
+  if (usedTokens > boundedTokenBudget) {
+    effectiveDescription = effectiveDescription.slice(0, Math.max(120, boundedTokenBudget * 4));
+    usedTokens = boundedTokenBudget;
+    uncertaintyNotes.push('Token budget guardrail trimmed input context before recommendation.');
+  }
+
+  if ((Date.now() - startedAt) > boundedTimeoutMs) {
+    return buildFallbackRecommendation({
+      stackFileNames,
+      blueprintFileNames,
+      tokenBudget: boundedTokenBudget,
+      timeoutMs: boundedTimeoutMs,
+      usedTokens,
+      elapsedMs: Date.now() - startedAt,
+      timeoutTriggered: true,
+    });
+  }
+
+  const detectionScoreByStackFileName = new Map();
+  for (const rankedCandidate of projectDetection?.rankedCandidates || []) {
+    const confidenceScore = Number(rankedCandidate.confidenceScore) || 0;
+    if (confidenceScore <= 0) {
+      continue;
+    }
+
+    detectionScoreByStackFileName.set(
+      rankedCandidate.stackFileName,
+      confidenceScore * 1.75
+    );
+  }
+
+  const scoredStackCandidates = stackFileNames.map((stackFileName) => {
+    const configuredSignals = STACK_SIGNAL_WEIGHTS[stackFileName] || [];
+    const matchedSignals = [];
+    let keywordSignalScore = 0;
+
+    for (const configuredSignal of configuredSignals) {
+      if (!effectiveDescription.includes(configuredSignal.term)) {
+        continue;
+      }
+
+      keywordSignalScore += configuredSignal.weight;
+      matchedSignals.push(configuredSignal.term);
+    }
+
+    const detectionSignalScore = detectionScoreByStackFileName.get(stackFileName) || 0;
+    const totalScore = 0.2 + keywordSignalScore + detectionSignalScore;
+
+    return {
+      stackFileName,
+      totalScore,
+      keywordSignalScore,
+      detectionSignalScore,
+      matchedSignals,
+    };
+  }).sort((leftCandidate, rightCandidate) => rightCandidate.totalScore - leftCandidate.totalScore);
+
+  if (scoredStackCandidates.length === 0) {
+    return buildFallbackRecommendation({
+      stackFileNames,
+      blueprintFileNames,
+      tokenBudget: boundedTokenBudget,
+      timeoutMs: boundedTimeoutMs,
+      usedTokens,
+      elapsedMs: Date.now() - startedAt,
+      timeoutTriggered: false,
+    });
+  }
+
+  const strongestCandidate = scoredStackCandidates[0];
+  const secondCandidate = scoredStackCandidates[1] || null;
+  const scoreGap = secondCandidate
+    ? strongestCandidate.totalScore - secondCandidate.totalScore
+    : strongestCandidate.totalScore;
+
+  let confidenceScore = 0.55
+    + Math.min(strongestCandidate.totalScore / 8, 0.25)
+    + Math.min(Math.max(scoreGap, 0) / 3, 0.18);
+
+  if (strongestCandidate.matchedSignals.length === 0) {
+    confidenceScore -= 0.2;
+  }
+
+  if (secondCandidate && scoreGap < 0.18) {
+    confidenceScore -= 0.1;
+  }
+
+  confidenceScore = clampNumericValue(confidenceScore, 0.35, 0.97);
+
+  const confidenceLabel = resolveConfidenceLabel(confidenceScore);
+  const lowConfidence = confidenceScore < 0.7;
+  const dataConflict = Boolean(secondCandidate && scoreGap < 0.18);
+
+  if (lowConfidence) {
+    uncertaintyNotes.push('Low confidence: description did not map strongly to a single stack profile.');
+  }
+
+  if (dataConflict) {
+    uncertaintyNotes.push('Data conflict: top stack candidates are close, so trade-offs need manual confirmation.');
+  }
+
+  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 rationaleSentences = [
+    `I recommend ${toTitleCase(recommendedStackFileName)} with ${toTitleCase(recommendedBlueprintFileName)} for this project.`,
+    `The strongest evidence in your description is ${signalSummary}, combined with available repository signals.`,
+    `Main trade-off: ${STACK_TRADEOFF_SUMMARIES[recommendedStackFileName] || 'validate ecosystem fit before production rollout.'}`,
+  ];
+
+  if (lowConfidence) {
+    rationaleSentences.push('Confidence is low, so review alternatives before finalizing architecture.');
+  }
+
+  const alternatives = scoredStackCandidates
+    .slice(1, 3)
+    .map((stackCandidate) => {
+      const alternativeBlueprintFileName = resolveRecommendedBlueprintFileName(stackCandidate.stackFileName, blueprintFileNames);
+      return {
+        stackFileName: stackCandidate.stackFileName,
+        blueprintFileName: alternativeBlueprintFileName,
+        oneLineTradeoff: STACK_TRADEOFF_SUMMARIES[stackCandidate.stackFileName]
+          || 'validate fit with your runtime and team constraints.',
+      };
+    });
+
+  const elapsedMs = Date.now() - startedAt;
+  if (elapsedMs > boundedTimeoutMs) {
+    return buildFallbackRecommendation({
+      stackFileNames,
+      blueprintFileNames,
+      tokenBudget: boundedTokenBudget,
+      timeoutMs: boundedTimeoutMs,
+      usedTokens,
+      elapsedMs,
+      timeoutTriggered: true,
+    });
+  }
+
+  return {
+    projectDescription: String(projectDescription || '').trim(),
+    recommendedStackFileName,
+    recommendedBlueprintFileName,
+    confidenceLabel,
+    confidenceScore: Number(confidenceScore.toFixed(2)),
+    rationaleSentences,
+    alternatives,
+    uncertaintyNotes,
+    signalSummary,
+    failureModes: {
+      lowConfidence,
+      dataConflict,
+      repeatedOverride: false,
+    },
+    researchBudget: {
+      tokenBudget: boundedTokenBudget,
+      timeoutMs: boundedTimeoutMs,
+      usedTokens: Math.min(usedTokens, boundedTokenBudget),
+      elapsedMs,
+      tokenBudgetCapped: usedTokens >= boundedTokenBudget,
+      timeoutTriggered: false,
+    },
+  };
+}
+
+export function formatArchitectureRecommendation(architectureRecommendation) {
+  const outputLines = [
+    '\nArchitecture recommendation (project-description-first):',
+    `- Stack: ${toTitleCase(architectureRecommendation.recommendedStackFileName)}`,
+    `- Blueprint: ${toTitleCase(architectureRecommendation.recommendedBlueprintFileName)}`,
+    `- Confidence: ${architectureRecommendation.confidenceLabel} (${architectureRecommendation.confidenceScore})`,
+    '- Rationale:',
+    ...architectureRecommendation.rationaleSentences.map((sentence, sentenceIndex) => `  ${sentenceIndex + 1}. ${sentence}`),
+    '- Alternatives:',
+  ];
+
+  if (architectureRecommendation.alternatives.length === 0) {
+    outputLines.push('  1. No strong alternatives detected from current input signals.');
+  } else {
+    outputLines.push(
+      ...architectureRecommendation.alternatives.map(
+        (alternative, alternativeIndex) => `  ${alternativeIndex + 1}. ${toTitleCase(alternative.stackFileName)} + ${toTitleCase(alternative.blueprintFileName)}: ${alternative.oneLineTradeoff}`
+      )
+    );
+  }
+
+  if (architectureRecommendation.uncertaintyNotes.length > 0) {
+    outputLines.push('- Uncertainty notes:');
+    outputLines.push(
+      ...architectureRecommendation.uncertaintyNotes.map(
+        (uncertaintyNote, uncertaintyIndex) => `  ${uncertaintyIndex + 1}. ${uncertaintyNote}`
+      )
+    );
+  }
+
+  const cautionLabels = [];
+  if (architectureRecommendation.failureModes.lowConfidence) {
+    cautionLabels.push('low-confidence');
+  }
+  if (architectureRecommendation.failureModes.dataConflict) {
+    cautionLabels.push('data-conflict');
+  }
+  if (architectureRecommendation.failureModes.repeatedOverride) {
+    cautionLabels.push('repeated-override');
+  }
+
+  if (cautionLabels.length > 0) {
+    outputLines.push(`- Caution labels: ${cautionLabels.join(', ')}`);
+  }
+
+  outputLines.push(
+    `- Research guardrails: ${architectureRecommendation.researchBudget.usedTokens}/${architectureRecommendation.researchBudget.tokenBudget} tokens, ${architectureRecommendation.researchBudget.elapsedMs}ms/${architectureRecommendation.researchBudget.timeoutMs}ms`
+  );
+
+  return outputLines.join('\n');
+}
+
+export async function readArchitectPreferenceState() {
+  if (!(await pathExists(ARCHITECT_PREFERENCE_FILE_PATH))) {
+    return null;
+  }
+
+  try {
+    const rawPreferenceContent = await fs.readFile(ARCHITECT_PREFERENCE_FILE_PATH, 'utf8');
+    const parsedPreferencePayload = JSON.parse(rawPreferenceContent);
+    const parsedPreferenceState = parsedPreferencePayload?.preference;
+
+    if (!parsedPreferenceState?.preferredStackFileName) {
+      return null;
+    }
+
+    return {
+      preferredStackFileName: parsedPreferenceState.preferredStackFileName,
+      preferredBlueprintFileName: parsedPreferenceState.preferredBlueprintFileName || null,
+      overrideCount: Number(parsedPreferenceState.overrideCount) || 0,
+      lastOverrideAt: parsedPreferenceState.lastOverrideAt || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function createUpdatedArchitectPreference(currentPreferenceState, {
+  selectedStackFileName,
+  selectedBlueprintFileName,
+}) {
+  const currentOverrideCount = Number(currentPreferenceState?.overrideCount) || 0;
+
+  return {
+    preferredStackFileName: selectedStackFileName,
+    preferredBlueprintFileName: selectedBlueprintFileName,
+    overrideCount: currentOverrideCount + 1,
+    lastOverrideAt: new Date().toISOString(),
+  };
+}
+
+export function shouldApplyRepeatedOverridePreference(preferenceState, recommendedStackFileName) {
+  if (!preferenceState?.preferredStackFileName) {
+    return false;
+  }
+
+  if ((Number(preferenceState.overrideCount) || 0) < 2) {
+    return false;
+  }
+
+  return preferenceState.preferredStackFileName !== recommendedStackFileName;
+}
+
+export async function writeArchitectPreferenceState(preferenceState) {
+  const preferencePayload = {
+    schemaVersion: '1.0.0',
+    updatedAt: new Date().toISOString(),
+    preference: {
+      preferredStackFileName: preferenceState.preferredStackFileName,
+      preferredBlueprintFileName: preferenceState.preferredBlueprintFileName,
+      overrideCount: preferenceState.overrideCount,
+      lastOverrideAt: preferenceState.lastOverrideAt,
+    },
+  };
+
+  await ensureDirectory(path.dirname(ARCHITECT_PREFERENCE_FILE_PATH));
+  await fs.writeFile(ARCHITECT_PREFERENCE_FILE_PATH, JSON.stringify(preferencePayload, null, 2) + '\n', 'utf8');
+}

package/lib/cli/commands/init.mjs

@@ -62,6 +62,20 @@ import {
   writeMemoryContinuityState,
 } from '../memory-continuity.mjs';
 import { evaluateSkillDomainCompatibility } from '../compatibility.mjs';
+import {
+  ARCHITECT_DEFAULT_TOKEN_BUDGET,
+  ARCHITECT_DEFAULT_TIMEOUT_MS,
+  ARCHITECT_MIN_TOKEN_BUDGET,
+  ARCHITECT_MAX_TOKEN_BUDGET,
+  ARCHITECT_MIN_TIMEOUT_MS,
+  ARCHITECT_MAX_TIMEOUT_MS,
+  recommendArchitecture,
+  formatArchitectureRecommendation,
+  readArchitectPreferenceState,
+  createUpdatedArchitectPreference,
+  shouldApplyRepeatedOverridePreference,
+  writeArchitectPreferenceState,
+} from '../architect.mjs';
 
 export { REPO_ROOT } from '../constants.mjs';
 
@@ -83,6 +97,9 @@ export function parseInitArguments(commandArguments) {
     docsLang: 'en',
     docsLangProvided: false,
     projectConfig: undefined,
+    projectDescription: '',
+    architectTokenBudget: ARCHITECT_DEFAULT_TOKEN_BUDGET,
+    architectTimeoutMs: ARCHITECT_DEFAULT_TIMEOUT_MS,
     runtimeEnv: 'auto',
     runtimeEnvProvided: false,
   };
@@ -242,6 +259,55 @@ export function parseInitArguments(commandArguments) {
       continue;
     }
 
+    if (currentArgument === '--project-description') {
+      parsedInitOptions.projectDescription = commandArguments[argumentIndex + 1] || '';
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--project-description=')) {
+      parsedInitOptions.projectDescription = currentArgument.split('=')[1] || '';
+      continue;
+    }
+
+    if (currentArgument === '--architect-token-budget') {
+      const rawTokenBudget = Number.parseInt(commandArguments[argumentIndex + 1], 10);
+      if (Number.isNaN(rawTokenBudget)) {
+        throw new Error('--architect-token-budget must be a number');
+      }
+      parsedInitOptions.architectTokenBudget = rawTokenBudget;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-token-budget=')) {
+      const rawTokenBudget = Number.parseInt(currentArgument.split('=')[1], 10);
+      if (Number.isNaN(rawTokenBudget)) {
+        throw new Error('--architect-token-budget must be a number');
+      }
+      parsedInitOptions.architectTokenBudget = rawTokenBudget;
+      continue;
+    }
+
+    if (currentArgument === '--architect-timeout-ms') {
+      const rawTimeoutMs = Number.parseInt(commandArguments[argumentIndex + 1], 10);
+      if (Number.isNaN(rawTimeoutMs)) {
+        throw new Error('--architect-timeout-ms must be a number');
+      }
+      parsedInitOptions.architectTimeoutMs = rawTimeoutMs;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--architect-timeout-ms=')) {
+      const rawTimeoutMs = Number.parseInt(currentArgument.split('=')[1], 10);
+      if (Number.isNaN(rawTimeoutMs)) {
+        throw new Error('--architect-timeout-ms must be a number');
+      }
+      parsedInitOptions.architectTimeoutMs = rawTimeoutMs;
+      continue;
+    }
+
     if (currentArgument === '--runtime-env') {
       parsedInitOptions.runtimeEnv = commandArguments[argumentIndex + 1] || 'auto';
       parsedInitOptions.runtimeEnvProvided = true;
@@ -272,6 +338,18 @@ export function parseInitArguments(commandArguments) {
     throw new Error('--runtime-env must be one of: auto, linux-wsl, linux, windows, macos');
   }
 
+  if (!Number.isInteger(parsedInitOptions.architectTokenBudget)
+    || parsedInitOptions.architectTokenBudget < ARCHITECT_MIN_TOKEN_BUDGET
+    || parsedInitOptions.architectTokenBudget > ARCHITECT_MAX_TOKEN_BUDGET) {
+    throw new Error(`--architect-token-budget must be an integer between ${ARCHITECT_MIN_TOKEN_BUDGET} and ${ARCHITECT_MAX_TOKEN_BUDGET}`);
+  }
+
+  if (!Number.isInteger(parsedInitOptions.architectTimeoutMs)
+    || parsedInitOptions.architectTimeoutMs < ARCHITECT_MIN_TIMEOUT_MS
+    || parsedInitOptions.architectTimeoutMs > ARCHITECT_MAX_TIMEOUT_MS) {
+    throw new Error(`--architect-timeout-ms must be an integer between ${ARCHITECT_MIN_TIMEOUT_MS} and ${ARCHITECT_MAX_TIMEOUT_MS}`);
+  }
+
   parsedInitOptions.docsLang = normalizedDocsLanguage;
   parsedInitOptions.runtimeEnv = normalizedRuntimeEnvironment;
   parsedInitOptions.tokenAgent = normalizeAgentName(parsedInitOptions.tokenAgent);
@@ -595,7 +673,11 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     let selectedAdditionalStackFileNames = [];
     let selectedAdditionalBlueprintFileNames = [];
 
-    const shouldAskManualStackSelection = !selectedStackFileNameFromOption
+    let architectureRecommendation = null;
+    let architectPreferenceState = await readArchitectPreferenceState();
+    let architectPreferenceUpdated = false;
+
+    const shouldRunArchitectureRecommendation = !selectedStackFileNameFromOption
       && !selectedPreset?.stack
       && !shouldAutoApplyDetectedStack
       && !selectedProfilePack?.defaultStackFileName
@@ -609,82 +691,113 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       selectedAdditionalStackFileNames = projectDetection.secondaryStackFileNames || [];
     }
 
-    if (shouldAskManualStackSelection) {
-      const selectedProjectScopeLabel = await askChoice(
-        'What are you building?',
-        PROJECT_SCOPE_CHOICES.map((scopeChoice) => scopeChoice.label),
-        userInterface
+    if (shouldRunArchitectureRecommendation) {
+      let architectureProjectDescription = String(initOptions.projectDescription || '').trim();
+
+      if (!architectureProjectDescription && isInteractiveSession) {
+        architectureProjectDescription = (await userInterface.question(
+          '\nDescribe your project in one short paragraph for architecture recommendation: '
+        )).trim();
+      }
+
+      if (!architectureProjectDescription) {
+        architectureProjectDescription = `A software project named ${path.basename(resolvedTargetDirectoryPath)}.`;
+      }
+
+      architectureRecommendation = recommendArchitecture({
+        projectDescription: architectureProjectDescription,
+        projectDetection,
+        stackFileNames,
+        blueprintFileNames,
+        tokenBudget: initOptions.architectTokenBudget,
+        timeoutMs: initOptions.architectTimeoutMs,
+      });
+
+      architectureRecommendation.userVeto = {
+        applied: false,
+        selectedStackFileName: architectureRecommendation.recommendedStackFileName,
+        selectedBlueprintFileName: architectureRecommendation.recommendedBlueprintFileName,
+        source: 'recommendation',
+      };
+
+      console.log(formatArchitectureRecommendation(architectureRecommendation));
+
+      const shouldSkipRecommendationDebate = shouldApplyRepeatedOverridePreference(
+        architectPreferenceState,
+        architectureRecommendation.recommendedStackFileName
       );
-      const selectedProjectScopeKey = resolveProjectScopeKeyFromLabel(selectedProjectScopeLabel);
-      const scopeStackFilter = PROJECT_SCOPE_STACK_FILTERS[selectedProjectScopeKey];
-      const scopedStackFileNames = filterStackFileNamesByCandidates(stackFileNames, scopeStackFilter);
 
-      if (selectedProjectScopeKey === 'web-application') {
-        const usesSplitWebStacks = await askYesNo(
-          'For this web project, do frontend and backend use different primary stacks?',
+      if (shouldSkipRecommendationDebate) {
+        architectureRecommendation.failureModes.repeatedOverride = true;
+        selectedManualStackFileName = stackFileNames.includes(architectPreferenceState.preferredStackFileName)
+          ? architectPreferenceState.preferredStackFileName
+          : architectureRecommendation.recommendedStackFileName;
+        selectedManualBlueprintFileName = blueprintFileNames.includes(architectPreferenceState.preferredBlueprintFileName)
+          ? architectPreferenceState.preferredBlueprintFileName
+          : architectureRecommendation.recommendedBlueprintFileName;
+        architectureRecommendation.userVeto = {
+          applied: true,
+          selectedStackFileName: selectedManualStackFileName,
+          selectedBlueprintFileName: selectedManualBlueprintFileName,
+          source: 'saved-preference',
+        };
+        console.log(
+          `Repeated override preference detected. Applying ${toTitleCase(selectedManualStackFileName)} + ${toTitleCase(selectedManualBlueprintFileName)} without additional debate.`
+        );
+      } else if (!isInteractiveSession) {
+        selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
+        selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
+      } else {
+        const shouldApplyRecommendedArchitecture = await askYesNo(
+          'Apply this architecture recommendation?',
           userInterface,
-          false
+          true
         );
 
-        if (usesSplitWebStacks) {
-          const selectableFrontendStacks = filterStackFileNamesByCandidates(scopedStackFileNames, WEB_FRONTEND_STACK_CANDIDATES);
-          const selectableBackendStacks = filterStackFileNamesByCandidates(scopedStackFileNames, WEB_BACKEND_STACK_CANDIDATES);
-
-          const selectedFrontendStackFileName = await askStackSelection(
-            'Which frontend stack should this governance pack target?',
-            selectableFrontendStacks,
+        if (shouldApplyRecommendedArchitecture) {
+          selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
+          selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
+        } else {
+          const vetoStackFileName = await askStackSelection(
+            'User veto received. Select stack to apply immediately:',
+            stackFileNames,
             userInterface
           );
-          const selectedBackendStackFileName = await askStackSelection(
-            'Which backend stack should this governance pack target?',
-            selectableBackendStacks,
+
+          const vetoBlueprintCandidates = filterBlueprintFileNamesByCandidates(
+            blueprintFileNames,
+            [BLUEPRINT_RECOMMENDATIONS[vetoStackFileName]].filter(Boolean)
+          );
+
+          const vetoBlueprintFileName = await askBlueprintSelection(
+            'Select blueprint to apply immediately (no further debate):',
+            vetoBlueprintCandidates,
             userInterface
           );
 
-          selectedManualStackFileName = selectedBackendStackFileName;
-          if (selectedFrontendStackFileName && selectedFrontendStackFileName !== selectedBackendStackFileName) {
-            selectedAdditionalStackFileNames = [selectedFrontendStackFileName];
-          }
+          selectedManualStackFileName = vetoStackFileName;
+          selectedManualBlueprintFileName = vetoBlueprintFileName;
+          architectureRecommendation.userVeto = {
+            applied: true,
+            selectedStackFileName: vetoStackFileName,
+            selectedBlueprintFileName: vetoBlueprintFileName,
+            source: 'interactive-veto',
+          };
+
+          architectPreferenceState = createUpdatedArchitectPreference(architectPreferenceState, {
+            selectedStackFileName: vetoStackFileName,
+            selectedBlueprintFileName: vetoBlueprintFileName,
+          });
+          architectPreferenceUpdated = true;
 
-          if (!selectedBlueprintFileNameFromOption && !selectedPreset?.blueprint) {
-            const selectableFrontendBlueprints = filterBlueprintFileNamesByCandidates(
-              blueprintFileNames,
-              WEB_FRONTEND_BLUEPRINT_CANDIDATES
-            );
-            const selectableBackendBlueprints = filterBlueprintFileNamesByCandidates(
-              blueprintFileNames,
-              WEB_BACKEND_BLUEPRINT_CANDIDATES
-            );
-
-            const selectedFrontendBlueprintFileName = await askBlueprintSelection(
-              'Which frontend blueprint should guide UI architecture?',
-              selectableFrontendBlueprints,
-              userInterface
-            );
-            const selectedBackendBlueprintFileName = await askBlueprintSelection(
-              'Which backend blueprint should guide service architecture?',
-              selectableBackendBlueprints,
-              userInterface
-            );
-
-            selectedManualBlueprintFileName = selectedBackendBlueprintFileName;
-            if (selectedFrontendBlueprintFileName && selectedFrontendBlueprintFileName !== selectedBackendBlueprintFileName) {
-              selectedAdditionalBlueprintFileNames = [selectedFrontendBlueprintFileName];
-            }
+          if (architectPreferenceState.overrideCount >= 2) {
+            architectureRecommendation.failureModes.repeatedOverride = true;
           }
-        } else {
-          selectedManualStackFileName = await askStackSelection(
-            'Which stack should this governance pack target?',
-            scopedStackFileNames,
-            userInterface
+
+          console.log(
+            `Veto applied. Proceeding with ${toTitleCase(vetoStackFileName)} + ${toTitleCase(vetoBlueprintFileName)} without recommendation loops.`
           );
         }
-      } else {
-        selectedManualStackFileName = await askStackSelection(
-          'Which stack should this governance pack target?',
-          scopedStackFileNames,
-          userInterface
-        );
       }
     }
 
@@ -724,6 +837,20 @@ 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(
       selectedAdditionalStackFileNames,
       blueprintFileNames,
@@ -916,8 +1043,13 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         adapters: memoryContinuityState?.adapters || [],
         stateFile: isMemoryContinuityEnabled ? '.agent-context/state/memory-continuity.json' : null,
       },
+      architectRecommendation: architectureRecommendation,
     });
 
+    if (architectPreferenceUpdated && architectPreferenceState) {
+      await writeArchitectPreferenceState(architectPreferenceState);
+    }
+
     console.log('\nInitialization complete.');
     console.log(`- Target directory: ${resolvedTargetDirectoryPath}`);
     console.log(`- Profile: ${selectedProfile.displayName}`);
@@ -927,6 +1059,16 @@ 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 (architectureRecommendation.userVeto?.applied) {
+        console.log(
+          `- User veto path: applied (${toTitleCase(architectureRecommendation.userVeto.selectedStackFileName)} + ${toTitleCase(architectureRecommendation.userVeto.selectedBlueprintFileName)})`
+        );
+      }
+    }
     console.log(`- Stack: ${toTitleCase(selectedResolvedStackFileName)}`);
     if (selectedAdditionalStackFileNames.length > 0) {
       console.log(`- Additional stacks: ${selectedAdditionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}`);

package/lib/cli/compiler.mjs

@@ -55,6 +55,7 @@ export async function writeOnboardingReport({
   operationMode = 'init',
   tokenOptimization = undefined,
   memoryContinuity = undefined,
+  architectRecommendation = null,
 }) {
   const onboardingReportPath = path.join(targetDirectoryPath, '.agent-context', 'state', 'onboarding-report.json');
   const resolvedTokenOptimization = typeof tokenOptimization === 'undefined'
@@ -86,6 +87,7 @@ export async function writeOnboardingReport({
     runtimeEnvironment,
     tokenOptimization: resolvedTokenOptimization,
     memoryContinuity: resolvedMemoryContinuity,
+    architectRecommendation,
     autoDetection: {
       recommendedStack: projectDetection.recommendedStackFileName,
       recommendedAdditionalStacks: projectDetection.secondaryStackFileNames || [],

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>] [--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>] [--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');
@@ -46,6 +46,9 @@ export function printUsage() {
   console.log('  --newbie     Legacy alias for --profile beginner');
   console.log('  --stack      Override stack selection');
   console.log('  --blueprint  Override blueprint selection');
+  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('  --ci         Override CI/CD 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.8",
+  "version": "2.5.10",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/frontend-usability-audit.mjs

@@ -20,6 +20,7 @@ const REQUIRED_FILES = [
   'docs/roadmap.md',
   'docs/v1.7-issue-breakdown.md',
   'docs/v1.7-execution-playbook.md',
+  '.agent-context/rules/frontend-architecture.md',
   '.agent-context/review-checklists/frontend-usability.md',
   '.agent-context/review-checklists/frontend-excellence-rubric.md',
 ];
@@ -43,9 +44,19 @@ const REQUIRED_EXCELLENCE_RUBRIC_SNIPPETS = [
   'Typography Quality',
   'Color System Diversity and Contrast',
   'Interaction Choreography',
+  'UX Narrative and Conversion Clarity',
+  'Template Diversity and Originality',
+  'Low-Diversity Template Output Policy',
   'Awwwards-level reference quality',
 ];
 
+const REQUIRED_FRONTEND_RULE_SNIPPETS = [
+  'Frontend Designer Mode (Auto Activation)',
+  'UI scope trigger signals',
+  'visual intent, interaction quality, and conversion clarity',
+  'template-only repetitive outputs',
+];
+
 function assertFileExists(relativeFilePath, failures) {
   const absoluteFilePath = resolve(REPOSITORY_ROOT, relativeFilePath);
   if (!existsSync(absoluteFilePath)) {
@@ -69,6 +80,7 @@ function runAudit() {
   }
 
   const roadmapPath = 'docs/roadmap.md';
+  const frontendRulePath = '.agent-context/rules/frontend-architecture.md';
   const checklistPath = '.agent-context/review-checklists/frontend-usability.md';
   const excellenceRubricPath = '.agent-context/review-checklists/frontend-excellence-rubric.md';
 
@@ -82,6 +94,11 @@ function runAudit() {
     assertContains('Checklist', checklistPath, checklistContent, REQUIRED_CHECKLIST_SNIPPETS, failures);
   }
 
+  if (existsSync(resolve(REPOSITORY_ROOT, frontendRulePath))) {
+    const frontendRuleContent = readFileSync(resolve(REPOSITORY_ROOT, frontendRulePath), 'utf8');
+    assertContains('Frontend rule', frontendRulePath, frontendRuleContent, REQUIRED_FRONTEND_RULE_SNIPPETS, failures);
+  }
+
   if (existsSync(resolve(REPOSITORY_ROOT, excellenceRubricPath))) {
     const excellenceRubricContent = readFileSync(resolve(REPOSITORY_ROOT, excellenceRubricPath), 'utf8');
     assertContains(

package/scripts/release-gate.mjs

@@ -42,6 +42,9 @@ const REQUIRED_FRONTEND_EXCELLENCE_RUBRIC_SNIPPETS = [
   'Typography Quality',
   'Color System Diversity and Contrast',
   'Interaction Choreography',
+  'UX Narrative and Conversion Clarity',
+  'Template Diversity and Originality',
+  'Low-Diversity Template Output Policy',
   'Awwwards-level reference quality',
 ];
 const BENCHMARK_GATE_SCRIPT_PATH = 'scripts/benchmark-gate.mjs';