@ryuenn3123/agentic-senior-core 3.0.9 → 3.0.10

package/lib/cli/project-scaffolder.mjs

@@ -306,6 +306,21 @@ function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
   return false;
 }
 
+const DESIGN_REQUIRED_SECTIONS = [
+  'Design Intent and Product Personality',
+  'Audience and Use-Context Signals',
+  'Visual Direction and Distinctive Moves',
+  'Color Science and Semantic Roles',
+  'Typographic Engineering and Hierarchy',
+  'Spacing, Layout Rhythm, and Density Strategy',
+  'Responsive Strategy and Cross-Viewport Adaptation Matrix',
+  'Interaction, Motion, and Feedback Rules',
+  'Component Language and Shared Patterns',
+  'Accessibility Non-Negotiables',
+  'Anti-Patterns to Avoid',
+  'Implementation Notes for Future UI Tasks',
+];
+
 function inferDesignKeywords(discoveryAnswers) {
   const normalizedDescription = String(discoveryAnswers.projectDescription || '').toLowerCase();
   const normalizedDomain = String(discoveryAnswers.primaryDomain || '').toLowerCase();
@@ -316,64 +331,114 @@ function inferDesignKeywords(discoveryAnswers) {
 
   if (aggregateText.includes('commerce') || aggregateText.includes('catalog') || aggregateText.includes('checkout')) {
     return {
+      designPhilosophy: 'Conversion clarity with premium restraint.',
       brandAdjectives: ['clear', 'desirable', 'confident'],
       antiAdjectives: ['cluttered', 'hesitant', 'coupon-noisy'],
+      typographyScaleRatio: '1.200',
+      baseGridUnit: 8,
+      densityMode: 'conversion-focused',
+      colorIntent: 'Use a restrained neutral foundation with one controlled accent reserved for buying cues and trust moments.',
       distinctiveMoves: [
         'Use product hierarchy and buying cues without turning the interface into a discount template.',
         'Keep decision-critical information prominent while secondary merchandising stays quiet.',
         'Let imagery and spacing create premium perception before decorative effects do.',
       ],
+      mutationRules: {
+        mobile: 'Convert browsing into vertically stacked product cards, move cart and filter actions into sticky or bottom-sheet patterns, and keep thumb-reach actions persistent.',
+        tablet: 'Preserve browsing flow with a two-column rhythm, collapse tertiary filters, and keep comparison moments visible without forcing desktop density.',
+        desktop: 'Expose multi-column merchandising, comparison views, and richer product context while keeping the purchase path visually dominant.',
+      },
     };
   }
 
   if (aggregateText.includes('dashboard') || aggregateText.includes('operations') || aggregateText.includes('report')) {
     return {
+      designPhilosophy: 'Operational calm under high information density.',
       brandAdjectives: ['calm', 'precise', 'trustworthy'],
       antiAdjectives: ['chaotic', 'gimmicky', 'visually exhausting'],
+      typographyScaleRatio: '1.125',
+      baseGridUnit: 4,
+      densityMode: 'high-density-scanning',
+      colorIntent: 'Use neutrals for structure and reserve accent saturation for status shifts, risky actions, and alerts.',
       distinctiveMoves: [
         'Prioritize scanning clarity and status recognition over decorative density.',
         'Use visual weight to separate signal from operational noise.',
         'Reserve strong accents for alerts, decisions, and state transitions only.',
       ],
+      mutationRules: {
+        mobile: 'Collapse dense tables into prioritized cards or row groups, move filters into drawers or sheets, and pin the most critical actions to the bottom reach zone.',
+        tablet: 'Keep two-column or split-pane workflows, collapse tertiary panels, and maintain fast scan paths for operators using touch or keyboard.',
+        desktop: 'Expose the highest-density views with visible navigation, comparison surfaces, and simultaneous context panels for power users.',
+      },
     };
   }
 
   if (aggregateText.includes('developer') || aggregateText.includes('api') || aggregateText.includes('platform')) {
     return {
+      designPhilosophy: 'Technical precision with explicit structure and honest feedback.',
       brandAdjectives: ['precise', 'technical', 'transparent'],
       antiAdjectives: ['vague', 'marketing-heavy', 'template-polished'],
+      typographyScaleRatio: '1.125',
+      baseGridUnit: 4,
+      densityMode: 'technical-utility',
+      colorIntent: 'Anchor the interface in disciplined neutrals and use accent color only where state, feedback, or code-adjacent interaction needs emphasis.',
       distinctiveMoves: [
         'Make structure and feedback feel exact without becoming sterile.',
         'Use code-adjacent rhythm and hierarchy to build trust with technical users.',
         'Keep complexity legible through spacing, grouping, and explicit interaction states.',
       ],
+      mutationRules: {
+        mobile: 'Switch multi-pane technical layouts into stacked sections, turn secondary navigation into segmented or sheet-based controls, and keep commands near the content they affect.',
+        tablet: 'Retain split-view comprehension where possible, compress chrome, and keep documentation or diagnostics adjacent to the active task.',
+        desktop: 'Expose full navigation, dense comparison surfaces, and multi-pane workflows for expert scanning and debugging.',
+      },
     };
   }
 
   if (aggregateText.includes('content') || aggregateText.includes('community') || aggregateText.includes('publish')) {
     return {
+      designPhilosophy: 'Editorial flow with warm but controlled expression.',
       brandAdjectives: ['editorial', 'warm', 'expressive'],
       antiAdjectives: ['flat', 'anonymous', 'feed-generic'],
+      typographyScaleRatio: '1.200',
+      baseGridUnit: 8,
+      densityMode: 'reading-first',
+      colorIntent: 'Let typography and surface contrast lead while chroma supports hierarchy and key participation actions.',
       distinctiveMoves: [
         'Build a strong reading rhythm so content feels curated rather than dumped into cards.',
         'Use contrast and spacing to guide attention between creation, moderation, and discovery.',
         'Give key interaction moments personality without sacrificing clarity.',
       ],
+      mutationRules: {
+        mobile: 'Prioritize reading and contribution flows in a single-column narrative stack, tuck secondary discovery tools behind sheets, and keep primary creation actions within reach.',
+        tablet: 'Balance narrative reading with supporting discovery modules, using two-column compositions only where hierarchy stays obvious.',
+        desktop: 'Use wider editorial compositions, visible secondary navigation, and modular discovery surfaces without breaking reading rhythm.',
+      },
     };
   }
 
   return {
+    designPhilosophy: 'Project-specific clarity with one authored tension.',
     brandAdjectives: ['clear', 'human', 'distinct'],
     antiAdjectives: ['generic', 'template-like', 'trend-chasing'],
+    typographyScaleRatio: '1.200',
+    baseGridUnit: 8,
+    densityMode: 'balanced-authored',
+    colorIntent: 'Use a restrained perceptual palette with one deliberate accent budget instead of interchangeable template colors.',
     distinctiveMoves: [
       'Create a visual direction with one memorable tension instead of stacking fashionable effects.',
       'Use rhythm, hierarchy, and motion intentionally so the interface feels authored.',
       'Keep the system flexible enough to evolve with product scope without losing identity.',
     ],
+    mutationRules: {
+      mobile: 'Stack primary tasks vertically, convert secondary navigation into thumb-friendly overlays or sheets, and simplify dense comparison layouts into progressive disclosure.',
+      tablet: 'Preserve hierarchy with fewer columns, condensed chrome, and adaptive navigation that maintains task continuity.',
+      desktop: 'Expose the full layout system, highest information density, and broadest navigation affordances without sacrificing clarity.',
+    },
   };
 }
 
-export function buildDesignIntentSeedFromSignals({
+function buildDesignIntentContractObject({
   projectName,
   projectDescription,
   primaryDomain,
@@ -390,7 +455,7 @@ export function buildDesignIntentSeedFromSignals({
   });
   const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
 
-  return `${JSON.stringify({
+  return {
     mode: 'dynamic',
     status,
     project: {
@@ -400,6 +465,7 @@ export function buildDesignIntentSeedFromSignals({
       stack: toTitleCase(initContext.stackFileName),
       blueprint: toTitleCase(initContext.blueprintFileName),
     },
+    designPhilosophy: inferredKeywords.designPhilosophy,
     brandAdjectives: inferredKeywords.brandAdjectives,
     antiAdjectives: inferredKeywords.antiAdjectives,
     visualDirection: {
@@ -407,41 +473,162 @@ export function buildDesignIntentSeedFromSignals({
       distinctiveMoves: inferredKeywords.distinctiveMoves,
       copiedReferenceAllowed: false,
     },
+    mathSystems: {
+      typographyScaleRatio: inferredKeywords.typographyScaleRatio,
+      baseGridUnit: inferredKeywords.baseGridUnit,
+      spacingPattern: designSignals?.spacingPattern || 'balanced-grid',
+      densityMode: inferredKeywords.densityMode,
+    },
+    colorTruth: {
+      format: 'OKLCH',
+      allowHexDerivatives: true,
+      requirePerceptualLightnessCurve: true,
+      paletteRoles: designSignals?.paletteRoles || ['base', 'surface', 'accent'],
+      intent: inferredKeywords.colorIntent,
+    },
+    crossViewportAdaptation: {
+      adaptByRecomposition: true,
+      touchTargetMinPx: 44,
+      mutationRules: inferredKeywords.mutationRules,
+    },
     experiencePrinciples: [
       'Design must feel project-specific, not interchangeable with generic SaaS templates.',
       'Major interface decisions must be explainable in product and user terms.',
       'Accessibility, responsiveness, and implementation realism are non-negotiable.',
+      'Cross-viewport behavior must reorganize tasks and navigation, not just scale the desktop layout down.',
     ],
     forbiddenPatterns: [
       'generic-saas-hero',
       'copycat-brand-system',
       'unjustified-default-gradients',
       'placeholder-design-language',
+      'scale-only-responsive-layout',
     ],
-    requiredDesignSections: [
-      'Design Intent and Product Personality',
-      'Audience and Use-Context Signals',
-      'Visual Direction and Distinctive Moves',
-      'Color System and Semantic Roles',
-      'Typography System and Hierarchy',
-      'Spacing, Layout Rhythm, and Density Strategy',
-      'Interaction, Motion, and Feedback Rules',
-      'Component Language and Shared Patterns',
-      'Accessibility Non-Negotiables',
-      'Responsive Strategy',
-      'Anti-Patterns to Avoid',
-      'Implementation Notes for Future UI Tasks',
-    ],
+    validationHints: {
+      rejectArbitraryHexOnlyPalette: true,
+      requireViewportMutationRules: true,
+      requirePerceptualColorRationale: true,
+      allowHexDerivatives: true,
+    },
+    requiredDesignSections: DESIGN_REQUIRED_SECTIONS,
     implementation: {
       requiredDeliverables: ['docs/DESIGN.md', 'docs/design-intent.json'],
       requireDesignRationale: true,
       requireDistinctVisualDirection: true,
       requireMachineReadableContract: true,
+      requireViewportMutationRules: true,
       bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
+      autoLoadedRuleFiles: [
+        '.agent-context/prompts/bootstrap-design.md',
+        '.agent-context/rules/frontend-architecture.md',
+      ],
+      disallowedAutoLoadedRuleFiles: [
+        '.agent-context/rules/database-design.md',
+        '.agent-context/rules/docker-runtime.md',
+        '.agent-context/rules/microservices.md',
+      ],
     },
     architectSignals: designSignals,
     ...supplementalFields,
-  }, null, 2)}\n`;
+  };
+}
+
+export function validateDesignIntentContract(designIntentContract) {
+  const validationErrors = [];
+
+  if (!designIntentContract || typeof designIntentContract !== 'object') {
+    return ['Design intent contract must be an object.'];
+  }
+
+  if (designIntentContract.mode !== 'dynamic') {
+    validationErrors.push('designIntent.mode must equal "dynamic".');
+  }
+
+  if (!designIntentContract.project || typeof designIntentContract.project !== 'object') {
+    validationErrors.push('designIntent.project must exist.');
+  }
+
+  if (!designIntentContract.designPhilosophy || typeof designIntentContract.designPhilosophy !== 'string') {
+    validationErrors.push('designIntent.designPhilosophy must be a non-empty string.');
+  }
+
+  if (!designIntentContract.mathSystems || typeof designIntentContract.mathSystems !== 'object') {
+    validationErrors.push('designIntent.mathSystems must exist.');
+  } else {
+    if (!/^\d+(\.\d+)?$/.test(String(designIntentContract.mathSystems.typographyScaleRatio || '').trim())) {
+      validationErrors.push('designIntent.mathSystems.typographyScaleRatio must be numeric text.');
+    }
+    if (!Number.isInteger(designIntentContract.mathSystems.baseGridUnit) || designIntentContract.mathSystems.baseGridUnit <= 0) {
+      validationErrors.push('designIntent.mathSystems.baseGridUnit must be a positive integer.');
+    }
+  }
+
+  if (!designIntentContract.colorTruth || typeof designIntentContract.colorTruth !== 'object') {
+    validationErrors.push('designIntent.colorTruth must exist.');
+  } else {
+    if (designIntentContract.colorTruth.format !== 'OKLCH') {
+      validationErrors.push('designIntent.colorTruth.format must equal "OKLCH".');
+    }
+    if (designIntentContract.colorTruth.allowHexDerivatives !== true) {
+      validationErrors.push('designIntent.colorTruth.allowHexDerivatives must equal true.');
+    }
+  }
+
+  if (!designIntentContract.crossViewportAdaptation || typeof designIntentContract.crossViewportAdaptation !== 'object') {
+    validationErrors.push('designIntent.crossViewportAdaptation must exist.');
+  } else {
+    const mutationRules = designIntentContract.crossViewportAdaptation.mutationRules;
+    if (!mutationRules || typeof mutationRules !== 'object') {
+      validationErrors.push('designIntent.crossViewportAdaptation.mutationRules must exist.');
+    } else {
+      for (const viewportKey of ['mobile', 'tablet', 'desktop']) {
+        if (!String(mutationRules[viewportKey] || '').trim()) {
+          validationErrors.push(`designIntent.crossViewportAdaptation.mutationRules.${viewportKey} must be a non-empty string.`);
+        }
+      }
+    }
+  }
+
+  if (!Array.isArray(designIntentContract.requiredDesignSections) || designIntentContract.requiredDesignSections.length !== DESIGN_REQUIRED_SECTIONS.length) {
+    validationErrors.push('designIntent.requiredDesignSections must match the required design contract sections.');
+  } else {
+    for (const requiredSectionName of DESIGN_REQUIRED_SECTIONS) {
+      if (!designIntentContract.requiredDesignSections.includes(requiredSectionName)) {
+        validationErrors.push(`designIntent.requiredDesignSections is missing "${requiredSectionName}".`);
+      }
+    }
+  }
+
+  return validationErrors;
+}
+
+export function buildDesignIntentSeedFromSignals({
+  projectName,
+  projectDescription,
+  primaryDomain,
+  features = [],
+  initContext,
+  architectureRecommendation = null,
+  status = 'seed-needs-design-synthesis',
+  supplementalFields = {},
+}) {
+  const designIntentContract = buildDesignIntentContractObject({
+    projectName,
+    projectDescription,
+    primaryDomain,
+    features,
+    initContext,
+    architectureRecommendation,
+    status,
+    supplementalFields,
+  });
+  const validationErrors = validateDesignIntentContract(designIntentContract);
+
+  if (validationErrors.length > 0) {
+    throw new Error(`Invalid design intent contract seed: ${validationErrors.join(' ')}`);
+  }
+
+  return `${JSON.stringify(designIntentContract, null, 2)}\n`;
 }
 
 function buildDesignIntentSeed({
@@ -572,13 +759,13 @@ function buildDesignBootstrapPrompt({
     '1. Design Vision and Product Personality',
     '2. Audience and Use-Context Signals',
     '3. Visual Direction and Distinctive Moves',
-    '4. Color System (tokens, semantic roles, accessibility rationale)',
-    '5. Typography System (pairing, scale, usage rules)',
+    '4. Color Science and Semantic Roles',
+    '5. Typographic Engineering and Hierarchy',
     '6. Spacing, Layout Rhythm, and Density Strategy',
-    '7. Motion and Interaction Principles',
-    '8. Component Language (cards, forms, nav, states)',
-    '9. Accessibility Non-Negotiables',
-    '10. Responsive Strategy',
+    '7. Responsive Strategy and Cross-Viewport Adaptation Matrix',
+    '8. Motion and Interaction Principles',
+    '9. Component Language (cards, forms, nav, states)',
+    '10. Accessibility Non-Negotiables',
     '11. Anti-Patterns to Avoid',
     '12. Implementation Notes for Future UI Tasks',
     '',
@@ -586,13 +773,18 @@ function buildDesignBootstrapPrompt({
     '1. mode',
     '2. status',
     '3. project',
-    '4. brandAdjectives',
-    '5. antiAdjectives',
-    '6. visualDirection',
-    '7. experiencePrinciples',
-    '8. forbiddenPatterns',
-    '9. requiredDesignSections',
-    '10. implementation',
+    '4. designPhilosophy',
+    '5. brandAdjectives',
+    '6. antiAdjectives',
+    '7. visualDirection',
+    '8. mathSystems',
+    '9. colorTruth',
+    '10. crossViewportAdaptation',
+    '11. experiencePrinciples',
+    '12. forbiddenPatterns',
+    '13. validationHints',
+    '14. requiredDesignSections',
+    '15. implementation',
     '',
     '## Hard Rules',
     '1. No copy-paste from external style guides.',
@@ -601,6 +793,9 @@ function buildDesignBootstrapPrompt({
     '4. Keep tone decisive like an art director, not generic AI boilerplate.',
     '5. Do not anchor the final design language to a famous brand reference. Translate inspiration into original project-specific principles.',
     '6. Reject interchangeable hero layouts, generic SaaS gradients, and trend-chasing decoration unless the project context explicitly justifies them.',
+    '7. Encode color intent in perceptual terms first. Hex values may exist only as implementation derivatives.',
+    '8. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
+    '9. Keep UI-only requests context-isolated. Load frontend design rules first and do not eagerly load backend-only rules unless the task explicitly crosses those boundaries.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.9",
+  "version": "3.0.10",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -43,6 +43,7 @@
   "scripts": {
     "init": "node ./bin/agentic-senior-core.js init",
     "audit:frontend-usability": "node ./scripts/frontend-usability-audit.mjs",
+    "audit:ui-design-judge": "node ./scripts/ui-design-judge.mjs",
     "audit:documentation-boundary": "node ./scripts/documentation-boundary-audit.mjs",
     "audit:context-triggered": "node ./scripts/context-triggered-audit.mjs",
     "audit:rules-guardian": "node ./scripts/rules-guardian-audit.mjs",

package/scripts/frontend-usability-audit.mjs

@@ -20,6 +20,9 @@ const REQUIRED_FILES = [
   'docs/roadmap.md',
   'docs/v1.7-issue-breakdown.md',
   'docs/v1.7-execution-playbook.md',
+  '.instructions.md',
+  '.agent-context/prompts/bootstrap-design.md',
+  'scripts/ui-design-judge.mjs',
   '.agent-context/rules/frontend-architecture.md',
   '.agent-context/review-checklists/pr-checklist.md',
   '.agent-context/review-checklists/architecture-review.md',
@@ -53,6 +56,28 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'UI Consistency Guardrails (Mandatory)',
   'Content language must stay consistent per screen and flow unless user requests multilingual output.',
   'Text color must remain contrast-safe against its background; no color collisions.',
+  'Responsive quality requires layout mutation and task reprioritization across breakpoints. Shrinking the desktop layout is not enough.',
+];
+
+const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
+  'UI Design Mode is context-isolated by default:',
+  'Responsive Strategy and Cross-Viewport Adaptation Matrix',
+  'colorTruth.format',
+  'crossViewportAdaptation.mutationRules.mobile/tablet/desktop',
+];
+
+const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
+  'Advisory-first UI design contract judge.',
+  'Default mode is advisory: findings never block release. Strict mode is opt-in.',
+  'Do not reward generic SaaS defaults or popular template patterns.',
+  'UI design judge only evaluates changed UI surfaces.',
+];
+
+const REQUIRED_INSTRUCTIONS_SNIPPETS = [
+  'UI Design Mode',
+  'bootstrap-design.md',
+  'frontend-architecture.md',
+  'do not eagerly load unrelated backend-only rules',
 ];
 
 function assertFileExists(relativeFilePath, failures) {
@@ -79,6 +104,8 @@ function runAudit() {
 
   const roadmapPath = 'docs/roadmap.md';
   const frontendRulePath = '.agent-context/rules/frontend-architecture.md';
+  const bootstrapDesignPromptPath = '.agent-context/prompts/bootstrap-design.md';
+  const instructionsPath = '.instructions.md';
   const prChecklistPath = '.agent-context/review-checklists/pr-checklist.md';
   const architectureChecklistPath = '.agent-context/review-checklists/architecture-review.md';
 
@@ -97,6 +124,33 @@ function runAudit() {
     assertContains('Frontend rule', frontendRulePath, frontendRuleContent, REQUIRED_FRONTEND_RULE_SNIPPETS, failures);
   }
 
+  if (existsSync(resolve(REPOSITORY_ROOT, bootstrapDesignPromptPath))) {
+    const bootstrapDesignPromptContent = readFileSync(resolve(REPOSITORY_ROOT, bootstrapDesignPromptPath), 'utf8');
+    assertContains(
+      'Bootstrap design prompt',
+      bootstrapDesignPromptPath,
+      bootstrapDesignPromptContent,
+      REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS,
+      failures
+    );
+  }
+
+  if (existsSync(resolve(REPOSITORY_ROOT, 'scripts/ui-design-judge.mjs'))) {
+    const uiDesignJudgeContent = readFileSync(resolve(REPOSITORY_ROOT, 'scripts/ui-design-judge.mjs'), 'utf8');
+    assertContains(
+      'UI design judge',
+      'scripts/ui-design-judge.mjs',
+      uiDesignJudgeContent,
+      REQUIRED_UI_DESIGN_JUDGE_SNIPPETS,
+      failures
+    );
+  }
+
+  if (existsSync(resolve(REPOSITORY_ROOT, instructionsPath))) {
+    const instructionsContent = readFileSync(resolve(REPOSITORY_ROOT, instructionsPath), 'utf8');
+    assertContains('Instructions', instructionsPath, instructionsContent, REQUIRED_INSTRUCTIONS_SNIPPETS, failures);
+  }
+
   if (existsSync(resolve(REPOSITORY_ROOT, architectureChecklistPath))) {
     const excellenceRubricContent = readFileSync(resolve(REPOSITORY_ROOT, architectureChecklistPath), 'utf8');
     assertContains(

package/scripts/release-gate.mjs

@@ -18,6 +18,7 @@ const REPOSITORY_ROOT = resolve(__dirname, '..');
 
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 const FRONTEND_AUDIT_SCRIPT_PATH = 'scripts/frontend-usability-audit.mjs';
+const UI_DESIGN_JUDGE_SCRIPT_PATH = 'scripts/ui-design-judge.mjs';
 const DOCUMENTATION_BOUNDARY_AUDIT_SCRIPT_PATH = 'scripts/documentation-boundary-audit.mjs';
 const CONTEXT_TRIGGERED_AUDIT_SCRIPT_PATH = 'scripts/context-triggered-audit.mjs';
 const RULES_GUARDIAN_AUDIT_SCRIPT_PATH = 'scripts/rules-guardian-audit.mjs';
@@ -716,6 +717,38 @@ function runReleaseGate() {
     pushResult(results, false, 'frontend-usability-audit', `Failed to execute frontend usability audit: ${frontendAuditErrorMessage}`);
   }
 
+  const uiDesignJudgeExecution = runMachineReadableScript(UI_DESIGN_JUDGE_SCRIPT_PATH);
+  if (!uiDesignJudgeExecution.report) {
+    const failureDetails = uiDesignJudgeExecution.executionErrorMessage
+      ? `UI design judge execution failed before producing a machine-readable report: ${uiDesignJudgeExecution.executionErrorMessage}`
+      : 'UI design judge did not produce machine-readable JSON output';
+    pushResult(results, false, 'ui-design-judge-advisory', failureDetails);
+  } else {
+    diagnostics.uiDesignJudge = uiDesignJudgeExecution.report;
+    pushResult(
+      results,
+      true,
+      'ui-design-judge-advisory',
+      `ui-design-judge executed (passed=${uiDesignJudgeExecution.report.passed}, skipped=${uiDesignJudgeExecution.report.skipped}, mode=${uiDesignJudgeExecution.report.mode})`
+    );
+
+    if (uiDesignJudgeExecution.report.advisoryOnly === true) {
+      pushResult(
+        results,
+        true,
+        'ui-design-judge-non-blocking-policy',
+        'UI design judge remains advisory by default and does not hard-block release gate'
+      );
+    } else {
+      pushResult(
+        results,
+        false,
+        'ui-design-judge-non-blocking-policy',
+        'UI design judge unexpectedly ran in blocking mode during release gate'
+      );
+    }
+  }
+
   const benchmarkGateExecution = runMachineReadableScript(BENCHMARK_GATE_SCRIPT_PATH);
   if (!benchmarkGateExecution.report) {
     const failureDetails = benchmarkGateExecution.executionErrorMessage