@ryuenn3123/agentic-senior-core 3.0.16 → 3.0.19

package/scripts/sync-thin-adapters.mjs

@@ -36,6 +36,18 @@ Canonical Snapshot SHA256: ${canonicalHash}
 This file is an adapter entrypoint for agent discovery.
 The canonical policy source is [.instructions.md](.instructions.md).
 
+If your host stops at this file instead of following the full chain, obey the Critical Bootstrap Floor below before coding.
+
+## Critical Bootstrap Floor
+
+- If \`.agent-instructions.md\` exists, prefer it immediately after this file because it is the compiled project-specific snapshot.
+- Memory continuity does not replace bootstrap loading. It is host-dependent project memory, not a guarantee that instructions were reloaded for this session.
+- For UI, UX, layout, screen, tailwind, frontend, or redesign requests: load [.agent-context/prompts/bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [.agent-context/rules/frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before editing code.
+- For UI scope: if \`docs/DESIGN.md\` or \`docs/design-intent.json\` is missing, materialize or refine them before implementing UI changes.
+- For refactor, improve, clean up, or fix requests: inspect the active rules and propose a plan before editing.
+- For new project or module requests: propose architecture before generating code.
+- For ecosystem, framework, dependency, or Docker claims: perform live web research instead of relying on stale local heuristics.
+
 ## Mandatory Bootstrap Chain
 
 1. Load [.instructions.md](.instructions.md) first as the canonical baseline.
@@ -66,6 +78,12 @@ Canonical Snapshot SHA256: ${canonicalHash}
 
 The canonical policy source for this repository is [.instructions.md](../.instructions.md).
 
+If your host stops at this file, follow this minimum floor:
+- Read \`.agent-instructions.md\` next when it exists.
+- For UI or redesign requests, load [.agent-context/prompts/bootstrap-design.md](../.agent-context/prompts/bootstrap-design.md) and [.agent-context/rules/frontend-architecture.md](../.agent-context/rules/frontend-architecture.md) before coding.
+- If UI scope and \`docs/DESIGN.md\` or \`docs/design-intent.json\` is missing, materialize them before UI implementation.
+- Memory continuity is host-dependent project memory and does not replace bootstrap loading.
+
 ## Required Load Order
 
 1. Read [.instructions.md](../.instructions.md) first as the canonical baseline.
@@ -91,6 +109,12 @@ Canonical Snapshot SHA256: ${canonicalHash}
 
 Canonical policy source: [.instructions.md](../.instructions.md).
 
+If your host stops at this file, follow this minimum floor:
+- Read \`.agent-instructions.md\` next when it exists.
+- For UI or redesign requests, load [.agent-context/prompts/bootstrap-design.md](../.agent-context/prompts/bootstrap-design.md) and [.agent-context/rules/frontend-architecture.md](../.agent-context/rules/frontend-architecture.md) before coding.
+- If UI scope and \`docs/DESIGN.md\` or \`docs/design-intent.json\` is missing, materialize them before UI implementation.
+- Memory continuity is host-dependent project memory and does not replace bootstrap loading.
+
 ## Bootstrap Sequence
 
 1. Load [.instructions.md](../.instructions.md) first as the canonical baseline.

package/scripts/ui-design-judge/constants.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const REPOSITORY_ROOT = resolve(__dirname, '..', '..');
+export const DESIGN_INTENT_PATH = resolve(REPOSITORY_ROOT, 'docs', 'design-intent.json');
+export const DESIGN_GUIDE_PATH = resolve(REPOSITORY_ROOT, 'docs', 'DESIGN.md');
+export const MAX_DIFF_CHARS = 12000;
+export const UI_FILE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.vue', '.css', '.scss', '.sass']);
+export const DESIGN_EXECUTION_REQUIRED_CAPABILITIES = [
+  'requireSurfacePlan',
+  'requireComponentGraph',
+  'requireViewportMutationPlan',
+  'requireInteractionStateMatrix',
+  'requireContentPriorityMap',
+  'requireTaskFlowNarrative',
+  'requireSignatureMoveRationale',
+  'requireStructuredHandoff',
+  'requireRepoEvidenceAlignment',
+];

package/scripts/ui-design-judge/design-execution-summary.mjs

@@ -0,0 +1,233 @@
+// @ts-check
+
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  DESIGN_EXECUTION_REQUIRED_CAPABILITIES,
+  DESIGN_GUIDE_PATH,
+  DESIGN_INTENT_PATH,
+} from './constants.mjs';
+
+export function normalizeStringArray(rawValue) {
+  if (!Array.isArray(rawValue)) {
+    return [];
+  }
+
+  return rawValue
+    .map((entryValue) => String(entryValue || '').trim())
+    .filter(Boolean);
+}
+
+export function loadDesignIntent() {
+  if (!existsSync(DESIGN_INTENT_PATH)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(DESIGN_INTENT_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function loadDesignGuide() {
+  if (!existsSync(DESIGN_GUIDE_PATH)) {
+    return '';
+  }
+
+  return readFileSync(DESIGN_GUIDE_PATH, 'utf8');
+}
+
+function hasRepoEvidenceSummary(designIntentContent) {
+  return Boolean(
+    designIntentContent?.repoEvidence?.designEvidenceSummary
+    && typeof designIntentContent.repoEvidence.designEvidenceSummary === 'object'
+  );
+}
+
+function summarizeDesignExecutionHandoff(designIntentContent) {
+  const designExecutionHandoff = designIntentContent?.designExecutionHandoff
+  && typeof designIntentContent.designExecutionHandoff === 'object'
+    ? designIntentContent.designExecutionHandoff
+    : {};
+
+  const surfacePlan = Array.isArray(designExecutionHandoff.surfacePlan)
+    ? designExecutionHandoff.surfacePlan
+    : [];
+  const componentGraphNodes = Array.isArray(designExecutionHandoff.componentGraph?.nodes)
+    ? designExecutionHandoff.componentGraph.nodes
+    : [];
+  const componentGraphEdges = Array.isArray(designExecutionHandoff.componentGraph?.edges)
+    ? designExecutionHandoff.componentGraph.edges
+    : [];
+  const interactionStateMatrix = Array.isArray(designExecutionHandoff.interactionStateMatrix)
+    ? designExecutionHandoff.interactionStateMatrix
+    : [];
+  const taskFlowNarrative = normalizeStringArray(designExecutionHandoff.taskFlowNarrative);
+  const contentPriorityMap = designExecutionHandoff.contentPriorityMap
+  && typeof designExecutionHandoff.contentPriorityMap === 'object'
+    ? designExecutionHandoff.contentPriorityMap
+    : {};
+  const viewportMutationPlan = designExecutionHandoff.viewportMutationPlan
+  && typeof designExecutionHandoff.viewportMutationPlan === 'object'
+    ? designExecutionHandoff.viewportMutationPlan
+    : {};
+
+  const artifactChecks = [
+    { name: 'surfacePlan', present: surfacePlan.length > 0 },
+    { name: 'componentGraphNodes', present: componentGraphNodes.length > 1 },
+    { name: 'componentGraphEdges', present: componentGraphEdges.length > 0 },
+    {
+      name: 'contentPriorityMap',
+      present: ['primary', 'secondary', 'deferred'].every((bucketKey) => Array.isArray(contentPriorityMap?.[bucketKey]) && contentPriorityMap[bucketKey].length > 0),
+    },
+    {
+      name: 'viewportMutationPlan',
+      present: ['mobile', 'tablet', 'desktop'].every((viewportKey) => String(viewportMutationPlan?.[viewportKey] || '').trim().length > 0),
+    },
+    { name: 'interactionStateMatrix', present: interactionStateMatrix.length > 0 },
+    { name: 'taskFlowNarrative', present: taskFlowNarrative.length > 1 },
+    { name: 'signatureMoveRationale', present: String(designExecutionHandoff.signatureMoveRationale || '').trim().length > 0 },
+  ];
+
+  const presentArtifacts = artifactChecks.filter((artifactCheck) => artifactCheck.present).map((artifactCheck) => artifactCheck.name);
+  const missingArtifacts = artifactChecks.filter((artifactCheck) => !artifactCheck.present).map((artifactCheck) => artifactCheck.name);
+  const implementationGuardrails = designExecutionHandoff.implementationGuardrails
+  && typeof designExecutionHandoff.implementationGuardrails === 'object'
+    ? designExecutionHandoff.implementationGuardrails
+    : {};
+
+  return {
+    present: Object.keys(designExecutionHandoff).length > 0,
+    version: typeof designExecutionHandoff.version === 'string' ? designExecutionHandoff.version : null,
+    handoffReady: (typeof designExecutionHandoff.version === 'string' && designExecutionHandoff.version === 'ui-handoff-v1')
+      && missingArtifacts.length === 0
+      && implementationGuardrails.requireBuildFromHandoff === true
+      && implementationGuardrails.requireGapNotesBeforeFallback === true
+      && implementationGuardrails.forbidGenericLayoutFallbackWithoutReason === true,
+    artifactCount: presentArtifacts.length,
+    presentArtifacts,
+    missingArtifacts,
+  };
+}
+
+export function summarizeDesignExecutionPolicy(designIntentContent) {
+  const designExecutionPolicy = designIntentContent?.designExecutionPolicy
+  && typeof designIntentContent.designExecutionPolicy === 'object'
+    ? designIntentContent.designExecutionPolicy
+    : {};
+
+  const requiredCapabilities = DESIGN_EXECUTION_REQUIRED_CAPABILITIES.map((capability) => ({
+    name: capability,
+    enabled: designExecutionPolicy[capability] === true,
+  }));
+  const enabledCapabilities = requiredCapabilities
+    .filter((capability) => capability.enabled)
+    .map((capability) => capability.name);
+  const missingCapabilities = requiredCapabilities
+    .filter((capability) => !capability.enabled)
+    .map((capability) => capability.name);
+  const semanticReviewFocus = normalizeStringArray(designExecutionPolicy.semanticReviewFocus);
+  const representationStrategy = typeof designExecutionPolicy.representationStrategy === 'string'
+    ? designExecutionPolicy.representationStrategy
+    : null;
+  const repoEvidenceAvailable = hasRepoEvidenceSummary(designIntentContent);
+  const screenshotDependencyForbidden = designExecutionPolicy.forbidScreenshotDependency === true;
+  const handoffFormatVersion = typeof designExecutionPolicy.handoffFormatVersion === 'string'
+    ? designExecutionPolicy.handoffFormatVersion
+    : null;
+  const handoffSummary = summarizeDesignExecutionHandoff(designIntentContent);
+  const policyPresent = Object.keys(designExecutionPolicy).length > 0;
+  const contractReady = policyPresent
+    && representationStrategy === 'surface-plan-v1'
+    && handoffFormatVersion === 'ui-handoff-v1'
+    && missingCapabilities.length === 0
+    && semanticReviewFocus.length >= 4
+    && screenshotDependencyForbidden
+    && handoffSummary.handoffReady
+    && repoEvidenceAvailable;
+
+  const notes = [];
+  if (!policyPresent) {
+    notes.push('designExecutionPolicy is missing from docs/design-intent.json.');
+  }
+  if (representationStrategy !== 'surface-plan-v1') {
+    notes.push('Structured design execution should declare representationStrategy "surface-plan-v1".');
+  }
+  if (handoffFormatVersion !== 'ui-handoff-v1') {
+    notes.push('Structured design execution should declare handoffFormatVersion "ui-handoff-v1".');
+  }
+  if (missingCapabilities.length > 0) {
+    notes.push(`Structured design execution is missing required capabilities: ${missingCapabilities.join(', ')}.`);
+  }
+  if (semanticReviewFocus.length < 4) {
+    notes.push('Structured design execution should declare semantic review focus dimensions before UI implementation review.');
+  }
+  if (!screenshotDependencyForbidden) {
+    notes.push('Structured design execution must explicitly forbid screenshot dependency as a baseline requirement.');
+  }
+  if (!handoffSummary.handoffReady) {
+    notes.push(`Structured design handoff is incomplete: ${handoffSummary.missingArtifacts.join(', ') || 'missing or invalid handoff metadata'}.`);
+  }
+  if (!repoEvidenceAvailable) {
+    notes.push('repoEvidence.designEvidenceSummary is missing or unreadable.');
+  }
+  if (notes.length === 0) {
+    notes.push('Structured design execution policy is present and ready for contract review.');
+  }
+
+  return {
+    policyPresent,
+    representationStrategy,
+    contractReady,
+    screenshotDependencyForbidden,
+    repoEvidenceAvailable,
+    handoffPresent: handoffSummary.present,
+    handoffVersion: handoffSummary.version,
+    handoffReady: handoffSummary.handoffReady,
+    handoffArtifactCount: handoffSummary.artifactCount,
+    presentHandoffArtifacts: handoffSummary.presentArtifacts,
+    missingHandoffArtifacts: handoffSummary.missingArtifacts,
+    repoEvidenceSummaryVersion: repoEvidenceAvailable
+      ? String(designIntentContent.repoEvidence.designEvidenceSummary.summaryVersion || '')
+      : null,
+    requiredCapabilities: requiredCapabilities.map((capability) => capability.name),
+    enabledCapabilities,
+    missingCapabilities,
+    semanticReviewFocus,
+    notes,
+  };
+}
+
+export function summarizeReviewRubric(designIntentContent) {
+  const reviewRubric = designIntentContent?.reviewRubric && typeof designIntentContent.reviewRubric === 'object'
+    ? designIntentContent.reviewRubric
+    : {};
+
+  const dimensions = Array.isArray(reviewRubric.dimensions)
+    ? reviewRubric.dimensions
+      .map((dimension) => ({
+        key: String(dimension?.key || '').trim(),
+        blockingByDefault: dimension?.blockingByDefault === true,
+        question: String(dimension?.question || '').trim(),
+      }))
+      .filter((dimension) => Boolean(dimension.key))
+    : [];
+
+  return {
+    version: typeof reviewRubric.version === 'string' ? reviewRubric.version : null,
+    dimensions,
+    genericitySignals: normalizeStringArray(reviewRubric.genericitySignals),
+    validBoldSignals: normalizeStringArray(reviewRubric.validBoldSignals),
+    reportingRules: reviewRubric.reportingRules && typeof reviewRubric.reportingRules === 'object'
+      ? {
+        mustExplainGenericity: reviewRubric.reportingRules.mustExplainGenericity === true,
+        mustSeparateTasteFromFailure: reviewRubric.reportingRules.mustSeparateTasteFromFailure === true,
+        contractFidelityOverridesPersonalTaste: reviewRubric.reportingRules.contractFidelityOverridesPersonalTaste === true,
+      }
+      : {
+        mustExplainGenericity: false,
+        mustSeparateTasteFromFailure: false,
+        contractFidelityOverridesPersonalTaste: false,
+      },
+  };
+}

package/scripts/ui-design-judge/git-input.mjs

@@ -0,0 +1,131 @@
+// @ts-check
+
+import { execSync } from 'node:child_process';
+import { extname } from 'node:path';
+import { REPOSITORY_ROOT, UI_FILE_EXTENSIONS } from './constants.mjs';
+
+export function detectCiProvider() {
+  if (process.env.GITHUB_ACTIONS === 'true') {
+    return 'github';
+  }
+
+  if (process.env.GITLAB_CI === 'true') {
+    return 'gitlab';
+  }
+
+  return 'local';
+}
+
+function collectGitDiff(baseSha, headSha) {
+  const execOptions = {
+    cwd: REPOSITORY_ROOT,
+    encoding: /** @type {'utf-8'} */ ('utf-8'),
+    maxBuffer: 1024 * 1024 * 8,
+  };
+
+  return execSync(`git diff "${baseSha}...${headSha}"`, execOptions);
+}
+
+function collectGitChangedFiles(baseSha, headSha) {
+  const execOptions = {
+    cwd: REPOSITORY_ROOT,
+    encoding: /** @type {'utf-8'} */ ('utf-8'),
+    maxBuffer: 1024 * 1024 * 2,
+  };
+
+  const output = execSync(`git diff --name-only "${baseSha}...${headSha}"`, execOptions);
+  return output
+    .split(/\r?\n/u)
+    .map((filePath) => filePath.trim())
+    .filter(Boolean);
+}
+
+export function collectPullRequestDiff() {
+  if (process.env.PR_DIFF) {
+    return process.env.PR_DIFF;
+  }
+
+  const githubBaseSha = process.env.GITHUB_BASE_SHA;
+  const githubHeadSha = process.env.GITHUB_HEAD_SHA ?? 'HEAD';
+  if (githubBaseSha) {
+    return collectGitDiff(githubBaseSha, githubHeadSha);
+  }
+
+  const gitlabBaseSha = process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+  const gitlabHeadSha = process.env.CI_COMMIT_SHA ?? 'HEAD';
+  if (gitlabBaseSha) {
+    return collectGitDiff(gitlabBaseSha, gitlabHeadSha);
+  }
+
+  try {
+    return execSync('git diff HEAD~1 HEAD', {
+      cwd: REPOSITORY_ROOT,
+      encoding: /** @type {'utf-8'} */ ('utf-8'),
+      maxBuffer: 1024 * 1024 * 8,
+    });
+  } catch {
+    try {
+      const emptyTreeSha = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+      return execSync(`git diff "${emptyTreeSha}" HEAD`, {
+        cwd: REPOSITORY_ROOT,
+        encoding: /** @type {'utf-8'} */ ('utf-8'),
+        maxBuffer: 1024 * 1024 * 8,
+      });
+    } catch {
+      return '';
+    }
+  }
+}
+
+export function collectChangedFiles() {
+  if (process.env.PR_DIFF) {
+    const filePathSet = new Set();
+    for (const diffHeaderMatch of process.env.PR_DIFF.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gm)) {
+      filePathSet.add(diffHeaderMatch[2]);
+    }
+    return Array.from(filePathSet);
+  }
+
+  const githubBaseSha = process.env.GITHUB_BASE_SHA;
+  const githubHeadSha = process.env.GITHUB_HEAD_SHA ?? 'HEAD';
+  if (githubBaseSha) {
+    return collectGitChangedFiles(githubBaseSha, githubHeadSha);
+  }
+
+  const gitlabBaseSha = process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+  const gitlabHeadSha = process.env.CI_COMMIT_SHA ?? 'HEAD';
+  if (gitlabBaseSha) {
+    return collectGitChangedFiles(gitlabBaseSha, gitlabHeadSha);
+  }
+
+  try {
+    const output = execSync('git diff --name-only HEAD~1 HEAD', {
+      cwd: REPOSITORY_ROOT,
+      encoding: /** @type {'utf-8'} */ ('utf-8'),
+      maxBuffer: 1024 * 1024 * 2,
+    });
+    return output.split(/\r?\n/u).map((filePath) => filePath.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function isUiRelevantFilePath(filePath) {
+  const normalizedFilePath = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+  const fileExtension = extname(normalizedFilePath);
+
+  if (!UI_FILE_EXTENSIONS.has(fileExtension)) {
+    return false;
+  }
+
+  return (
+    normalizedFilePath.startsWith('src/')
+    || normalizedFilePath.startsWith('app/')
+    || normalizedFilePath.startsWith('pages/')
+    || normalizedFilePath.startsWith('components/')
+    || normalizedFilePath.startsWith('styles/')
+    || normalizedFilePath.includes('/components/')
+    || normalizedFilePath.includes('/screens/')
+    || normalizedFilePath.includes('/layouts/')
+  );
+}

package/scripts/ui-design-judge/prompting.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+
+import { MAX_DIFF_CHARS } from './constants.mjs';
+
+export function buildSystemPrompt() {
+  return [
+    'You are a Principal UI/UX Design Reviewer.',
+    'Compare the changed UI code against the provided design contract.',
+    'Treat docs/design-intent.json as the machine-readable source of truth.',
+    'Treat docs/DESIGN.md as explanatory context, not a generic style guide.',
+    'Treat designExecutionPolicy as the execution contract for how the UI should be planned, structured, and reviewed.',
+    'Treat designExecutionHandoff as the explicit bridge between design intent and implementation decisions.',
+    'Treat reviewRubric as the stable scoring frame for distinctiveness, contract fidelity, visual consistency, heuristic UX quality, and motion discipline.',
+    'Use repoEvidence.designEvidenceSummary as implementation evidence when deciding whether the diff follows the intended system.',
+    'Do not reward generic SaaS defaults or popular template patterns.',
+    'Do not penalize originality when the implementation still aligns with the contract.',
+    'Purposeful motion is allowed and can improve quality. Only flag motion when it drifts from the contract, ignores reduced-motion expectations, or adds avoidable performance/accessibility risk.',
+    'Only flag drift when there is a clear mismatch with the contract, accessibility non-negotiables, or cross-viewport adaptation rules.',
+    'Treat WCAG 2.2 AA failures as hard accessibility drift.',
+    'Treat APCA as advisory perceptual tuning only. Do not recommend blocking solely because APCA would prefer a stronger readability adjustment when WCAG hard requirements still pass.',
+    'Check focus visibility, focus appearance, target size, keyboard access, accessible authentication, and status or dynamic state access when the diff touches those surfaces.',
+    'This audit always runs in advisory mode for this repository workflow.',
+    'Focus on color intent, typographic hierarchy, responsive re-layout, purposeful motion, component morphology across states, interaction behavior, and genericity drift.',
+    'If you call something generic, explain the specific genericity signal or anti-pattern that caused that judgment.',
+    'Separate taste from failure. A bold design that follows the contract should not be penalized only because it is unusual.',
+    'Return ONLY one JSON object on a single line prefixed with JSON_VERDICT:.',
+    'Schema:',
+    '{"alignmentScore": number|null, "genericityAssessment": {"status": "distinctive|mixed|generic|unclear", "reason": string}, "tasteVsFailureSeparated": boolean, "rubricBreakdown": [{"dimension": string, "score": number|null, "verdict": "strong|acceptable|weak|unclear", "reason": string, "blocking": boolean}], "notes": string[], "findings": [{"area": string, "severity": "high|medium|low", "problem": string, "evidence": string, "recommendation": string, "blockingRecommended": boolean}]}',
+  ].join('\n');
+}
+
+export function buildUserMessage(designIntentContent, designGuideContent, diffContent, changedUiFiles, designExecutionSummary) {
+  const truncatedDiff = diffContent.length > MAX_DIFF_CHARS
+    ? `${diffContent.slice(0, MAX_DIFF_CHARS)}\n\n[DIFF TRUNCATED - ${diffContent.length - MAX_DIFF_CHARS} additional characters omitted]`
+    : diffContent;
+
+  return [
+    '## Changed UI Files',
+    changedUiFiles.length > 0 ? changedUiFiles.map((filePath) => `- ${filePath}`).join('\n') : '- none',
+    '',
+    '## design-intent.json',
+    '```json',
+    JSON.stringify(designIntentContent, null, 2),
+    '```',
+    '',
+    '## Review Rubric',
+    '```json',
+    JSON.stringify(designIntentContent?.reviewRubric || null, null, 2),
+    '```',
+    '',
+    '## Structured Design Handoff',
+    '```json',
+    JSON.stringify(designIntentContent?.designExecutionHandoff || null, null, 2),
+    '```',
+    '',
+    '## DESIGN.md',
+    '```md',
+    designGuideContent.trim() || '(missing DESIGN.md)',
+    '```',
+    '',
+    '## Structured Design Execution Summary',
+    '```json',
+    JSON.stringify(designExecutionSummary, null, 2),
+    '```',
+    '',
+    '## UI Diff',
+    '```diff',
+    truncatedDiff.trim() || '(no UI diff)',
+    '```',
+    '',
+    'Judge alignment to the contract. Avoid aesthetic bias toward generic web trends or toward motionless/static outputs.',
+  ].join('\n');
+}

package/scripts/ui-design-judge/providers.mjs

@@ -0,0 +1,102 @@
+// @ts-check
+
+async function callOpenAiProvider(systemPrompt, userMessage) {
+  const selectedModel = process.env.LLM_JUDGE_MODEL ?? 'gpt-4o-mini';
+  const apiResponse = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: selectedModel,
+      max_tokens: 2048,
+      temperature: 0,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage },
+      ],
+    }),
+  });
+
+  if (!apiResponse.ok) {
+    const errorBody = await apiResponse.text();
+    throw new Error(`OpenAI API returned ${apiResponse.status}: ${errorBody}`);
+  }
+
+  const responsePayload = await apiResponse.json();
+  return responsePayload.choices[0].message.content;
+}
+
+async function callAnthropicProvider(systemPrompt, userMessage) {
+  const selectedModel = process.env.LLM_JUDGE_MODEL ?? 'claude-3-5-haiku-latest';
+  const apiResponse = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': process.env.ANTHROPIC_API_KEY ?? '',
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: selectedModel,
+      max_tokens: 2048,
+      system: systemPrompt,
+      messages: [{ role: 'user', content: userMessage }],
+    }),
+  });
+
+  if (!apiResponse.ok) {
+    const errorBody = await apiResponse.text();
+    throw new Error(`Anthropic API returned ${apiResponse.status}: ${errorBody}`);
+  }
+
+  const responsePayload = await apiResponse.json();
+  return responsePayload.content[0].text;
+}
+
+async function callGeminiProvider(systemPrompt, userMessage) {
+  const selectedModel = process.env.LLM_JUDGE_MODEL ?? 'gemini-2.0-flash';
+  const apiKey = process.env.GEMINI_API_KEY ?? '';
+  const endpointUrl = `https://generativelanguage.googleapis.com/v1beta/models/${selectedModel}:generateContent?key=${apiKey}`;
+
+  const apiResponse = await fetch(endpointUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      system_instruction: { parts: [{ text: systemPrompt }] },
+      contents: [{ role: 'user', parts: [{ text: userMessage }] }],
+      generationConfig: { temperature: 0, maxOutputTokens: 2048 },
+    }),
+  });
+
+  if (!apiResponse.ok) {
+    const errorBody = await apiResponse.text();
+    throw new Error(`Gemini API returned ${apiResponse.status}: ${errorBody}`);
+  }
+
+  const responsePayload = await apiResponse.json();
+  return responsePayload.candidates[0].content.parts[0].text;
+}
+
+export function selectAvailableProvider() {
+  if (process.env.UI_DESIGN_JUDGE_MOCK_RESPONSE) {
+    return {
+      providerName: 'mock',
+      invokeProvider: async () => process.env.UI_DESIGN_JUDGE_MOCK_RESPONSE,
+    };
+  }
+
+  if (process.env.OPENAI_API_KEY) {
+    return { providerName: 'openai', invokeProvider: callOpenAiProvider };
+  }
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    return { providerName: 'anthropic', invokeProvider: callAnthropicProvider };
+  }
+
+  if (process.env.GEMINI_API_KEY) {
+    return { providerName: 'gemini', invokeProvider: callGeminiProvider };
+  }
+
+  return null;
+}