@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -29,174 +29,56 @@ export function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
   return false;
 }
 
-function inferDesignKeywords(discoveryAnswers) {
-  const normalizedDescription = String(discoveryAnswers.projectDescription || '').toLowerCase();
-  const normalizedDomain = String(discoveryAnswers.primaryDomain || '').toLowerCase();
-  const normalizedFeatures = Array.isArray(discoveryAnswers.features)
-    ? discoveryAnswers.features.map((featureValue) => String(featureValue).toLowerCase()).join(' ')
-    : '';
-  const aggregateText = `${normalizedDescription} ${normalizedDomain} ${normalizedFeatures}`;
-
-  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.',
-      ],
-      motionPurpose: 'Use motion to reinforce buying confidence, product continuity, and premium delight. It may be theatrical at key moments if it stays fast, legible, and supportive of decision-making.',
-      motionChoreography: 'Favor fast hover and focus feedback, confident sheet choreography, product-media continuity, and one or two signature reveal moments. Avoid autoplay spectacle that distracts from purchase decisions.',
-      motionDurations: {
-        desktop: 180,
-        mobile: 240,
-      },
-      componentMorphology: {
-        mobile: 'Product cards should compress supporting metadata, pin purchase actions closer to the thumb zone, and move comparison into progressive disclosure or bottom sheets.',
-        tablet: 'Cards and merch modules should preserve comparison affordances while reducing tertiary chrome and keeping visual hierarchy stable.',
-        desktop: 'Cards can expand media, comparison, and reassurance copy while keeping buying cues dominant and visually disciplined.',
-      },
-      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.',
-      ],
-      motionPurpose: 'Use motion as operational feedback and state continuity, while still allowing decisive state transitions that make dense workflows feel alive and controlled.',
-      motionChoreography: 'Prefer fast transitions for filters, drawers, status reveals, and row expansion, but allow strong confirmation moments when they improve confidence and scan clarity.',
-      motionDurations: {
-        desktop: 160,
-        mobile: 220,
-      },
-      componentMorphology: {
-        mobile: 'Data rows should become prioritized cards or grouped summaries, with filters and secondary tools moving into sheets or drawers.',
-        tablet: 'Operational panels should retain split-view logic where possible, while tertiary panels collapse behind explicit toggles.',
-        desktop: 'Dense tables, side panels, and comparison surfaces can remain visible simultaneously, with state treatments optimized for rapid scanning.',
-      },
-      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.',
-      ],
-      motionPurpose: 'Use motion to clarify causality, reveal system state, preserve context, and give technical workflows a sense of precision instead of dead stillness.',
-      motionChoreography: 'Prefer sharp panel transitions, command feedback, disclosure motion, and occasional signature transitions that feel exact rather than ornamental.',
-      motionDurations: {
-        desktop: 170,
-        mobile: 230,
-      },
-      componentMorphology: {
-        mobile: 'Technical panes should flatten into sequential sections, with commands and diagnostics colocated near the content they affect.',
-        tablet: 'Split views should survive where useful, with explicit panel toggles and condensed chrome for code-adjacent tasks.',
-        desktop: 'Navigation, documentation, diagnostics, and active work surfaces can remain concurrently visible when it improves expert comprehension.',
-      },
-      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.',
-      ],
-      motionPurpose: 'Use motion to support reading rhythm, reveal structure, and reward contribution moments with visible craft, not generic restraint.',
-      motionChoreography: 'Favor reveal choreography for section transitions, expressive but measured feedback on participation, and media behavior that feels alive without becoming noisy.',
-      motionDurations: {
-        desktop: 190,
-        mobile: 250,
-      },
-      componentMorphology: {
-        mobile: 'Reading surfaces should dominate while secondary discovery and community tools collapse behind sheets, tabs, or segmented controls.',
-        tablet: 'Editorial modules can balance reading and discovery, provided the primary narrative flow remains obvious.',
-        desktop: 'Long-form content, secondary navigation, and related discovery modules can coexist without fragmenting the reading rhythm.',
-      },
-      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.',
-      },
-    };
-  }
+function buildStructureFirstSeedSignals({
+  projectName,
+  projectDescription,
+  primaryDomain,
+  supplementalFields = {},
+}) {
+  const normalizedDescription = String(projectDescription || '').trim();
+  const repoEvidenceSummary = supplementalFields?.repoEvidence?.designEvidenceSummary || null;
+  const hasRepoEvidence = Boolean(
+    repoEvidenceSummary
+    || (Array.isArray(supplementalFields?.repoEvidence?.workspaceUiEntries)
+      && supplementalFields.repoEvidence.workspaceUiEntries.length > 0)
+  );
+  const evidenceSourceLabel = hasRepoEvidence
+    ? 'current repo evidence, existing UI code, and the active brief'
+    : 'the active brief and any repo evidence available at synthesis time';
+  const projectContextLabel = normalizedDescription
+    ? `the product context "${normalizedDescription}"`
+    : 'the current product context';
 
   return {
-    designPhilosophy: 'Project-specific clarity with one authored tension and one memorable visual bet.',
-    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.',
+    designPhilosophy: `Use ${evidenceSourceLabel} to synthesize the design system for ${projectName || 'this project'}. This seed is only a decision scaffold: the LLM must choose the visual language, libraries, color system, typography, spacing, and interaction model from ${projectContextLabel}, current repo evidence, and live official documentation when a technology claim is needed.`,
+    brandAdjectives: ['agent-synthesized-from-current-context'],
+    antiAdjectives: ['offline-prescribed-style', 'template-by-default', 'scale-only-responsive', 'unresearched-library-choice'],
+    typographyScaleRatio: 'agent-calibrated-from-content-platform-and-readability',
+    baseGridUnit: 'agent-calibrated-from-platform-density-and-implementation-stack',
+    spacingPattern: 'agent-defined-from-task-flow-and-viewport-needs',
+    densityMode: 'agent-defined-from-user-task-device-and-content-pressure',
+    colorIntent: `Choose semantic palette roles from ${projectContextLabel}, current repo evidence, and accessibility needs. Do not inherit fixed palettes or generic SaaS color defaults from this scaffold.`,
+    paletteRoles: ['agent-defined-semantic-roles'],
     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.',
+      'Research and choose a current, project-fit visual direction instead of inheriting any offline preset from this scaffold.',
+      'Define at least one recognizable design move from the product task, audience, content, and repo evidence before implementation.',
+      'Document why the chosen move belongs to this project and which common LLM bad habit it intentionally avoids.',
     ],
-    motionPurpose: 'Allow motion to create continuity, feedback, perceived craft, and memorability. Optimize bold choreography instead of defaulting to restraint. Reject only motion that harms comprehension, accessibility, or runtime performance.',
-    motionChoreography: 'Use fast purposeful transitions for most interactions, but allow a small number of signature transitions or reveal moments when they strengthen product identity and remain technically cheap.',
+    motionPurpose: 'Use modern motion when it improves hierarchy, continuity, feedback, memorability, or perceived product quality. If implementation needs a motion library, the LLM must choose a current compatible option from official docs instead of relying on an offline default.',
+    motionChoreography: 'Define choreography from the product experience and implementation stack. Keep it performant and reduced-motion-safe; do not suppress rich interaction by default.',
     motionDurations: {
-      desktop: 180,
-      mobile: 240,
+      desktop: 'agent-calibrated',
+      mobile: 'agent-calibrated',
     },
     componentMorphology: {
-      mobile: 'Primary components should simplify structure, prioritize direct tasks, and collapse supporting detail into explicit disclosure.',
-      tablet: 'Components should preserve hierarchy and task continuity while reducing density and compressing tertiary chrome.',
-      desktop: 'Components can expose richer states, denser supporting information, and broader navigation affordances without losing clarity.',
+      mobile: 'Recompose the experience for touch, task priority, and constrained attention. Mobile should be a deliberate mobile design, not a shrunken desktop.',
+      tablet: 'Regroup surfaces for medium-width use, preserving task clarity without cloning either desktop or mobile blindly.',
+      desktop: 'Use the available space to improve hierarchy, scanability, and interaction quality without defaulting to template grids or generic dashboard chrome.',
     },
     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.',
+      mobile: 'Define a mobile-specific composition with reordered, merged, or disclosed content where appropriate. Scale-only shrink behavior is failure.',
+      tablet: 'Define a tablet-specific regrouping strategy rather than a width-only reduction of desktop.',
+      desktop: 'Define a desktop composition that uses space intentionally and avoids generic equal-weight modules unless the project evidence justifies them.',
     },
   };
 }
@@ -207,47 +89,54 @@ function buildDesignIntentContractObject({
   primaryDomain,
   features = [],
   initContext,
-  architectureRecommendation = null,
   status = 'seed-needs-design-synthesis',
   supplementalFields = {},
 }) {
-  const inferredKeywords = inferDesignKeywords({
+  const inferredKeywords = buildStructureFirstSeedSignals({
+    projectName,
     projectDescription,
     primaryDomain,
     features,
+    supplementalFields,
   });
-  const normalizedPrimaryDomain = String(primaryDomain || '').trim().toLowerCase();
-  const resolvedSpacingPattern = inferredKeywords.densityMode === 'dense'
-    ? 'compact-grid'
-    : normalizedPrimaryDomain.includes('mobile')
-      ? 'mobile-first-single-axis'
-      : inferredKeywords.densityMode === 'focused'
-        ? 'high-contrast-rhythm'
-        : 'balanced-grid';
 
   return {
     mode: 'dynamic',
     status,
+    seedPolicy: {
+      mode: 'structure-first-scaffold',
+      requiresProjectSpecificRefinement: true,
+      forbidLiteralCarryoverAsFinalArtDirection: true,
+      repoEvidenceShouldOverrideSeedTaste: true,
+    },
     project: {
       name: projectName,
       context: projectDescription,
       domain: primaryDomain,
-      stack: toTitleCase(initContext.stackFileName),
-      blueprint: toTitleCase(initContext.blueprintFileName),
+      runtimeConstraint: initContext.stackFileName === 'agent-decision-runtime.md'
+        ? 'agent-recommendation-required'
+        : toTitleCase(initContext.stackFileName),
+      architectureConstraint: initContext.blueprintFileName === 'agent-decision-architecture.md'
+        ? 'agent-recommendation-required'
+        : toTitleCase(initContext.blueprintFileName),
     },
     designPhilosophy: inferredKeywords.designPhilosophy,
     brandAdjectives: inferredKeywords.brandAdjectives,
     antiAdjectives: inferredKeywords.antiAdjectives,
     visualDirection: {
-      trendStance: 'trend-aware-not-trend-chasing',
+      seedMode: 'scaffold-only',
+      requiresProjectSpecificSynthesis: true,
+      selectionAuthority: 'agent-llm-after-current-context-repo-evidence-and-live-official-docs',
+      trendStance: 'current-context-first-not-offline-preset-first',
       distinctiveMoves: inferredKeywords.distinctiveMoves,
       copiedReferenceAllowed: false,
     },
     mathSystems: {
       typographyScaleRatio: inferredKeywords.typographyScaleRatio,
       baseGridUnit: inferredKeywords.baseGridUnit,
-      spacingPattern: resolvedSpacingPattern,
+      spacingPattern: inferredKeywords.spacingPattern,
       densityMode: inferredKeywords.densityMode,
+      seedValuesRequireCalibration: true,
     },
     tokenSystem: {
       sourceOfTruth: 'docs/design-intent.json',
@@ -280,7 +169,10 @@ function buildDesignIntentContractObject({
       format: 'OKLCH',
       allowHexDerivatives: true,
       requirePerceptualLightnessCurve: true,
-      paletteRoles: ['base', 'surface', 'accent'],
+      paletteRoles: inferredKeywords.paletteRoles,
+      rolePolicy: 'minimum-semantic-scaffold',
+      rolesAreMinimumScaffold: true,
+      rolesMustBeAgentDefined: true,
       intent: inferredKeywords.colorIntent,
     },
     crossViewportAdaptation: {
@@ -294,6 +186,7 @@ function buildDesignIntentContractObject({
       choreography: inferredKeywords.motionChoreography,
       desktopDurationMs: inferredKeywords.motionDurations.desktop,
       mobileDurationMs: inferredKeywords.motionDurations.mobile,
+      seedToneLocked: false,
       respectReducedMotion: true,
       preferTransformAndOpacity: true,
       avoidDecorativeMotionForItsOwnSake: true,
@@ -301,6 +194,7 @@ function buildDesignIntentContractObject({
     componentMorphology: {
       requireStateBehaviorMatrix: true,
       preserveIdentityAcrossViewports: true,
+      seedBehaviorsRequireRefinement: true,
       stateKeys: ['default', 'hover', 'focus', 'active', 'disabled', 'loading', 'error'],
       viewportBehavior: inferredKeywords.componentMorphology,
     },
@@ -327,51 +221,204 @@ function buildDesignIntentContractObject({
         typographyReadabilityTuning: true,
       },
     },
-    visualQaPolicy: {
-      deterministicFirst: true,
-      baselineStrategy: 'deterministic-screenshots',
-      reportVersion: 'hybrid-visual-diff-v1',
-      requiredViewports: ['mobile', 'tablet', 'desktop'],
-      capturePlan: {
-        requireAboveFoldCapture: true,
-        requireFullPageCapture: true,
-        requireSectionCapturesForLongPages: true,
-        longPageStrategy: 'anchor-plus-tiles',
-        minimumSectionCaptureCount: 3,
-        maxViewportHeightsPerTile: 3,
-        tileOverlapRatio: 0.15,
-        requiredSectionTypes: [
-          'hero-or-primary-action',
-          'midpage-proof-or-content',
-          'footer-or-terminal-state',
+    designExecutionPolicy: {
+      representationStrategy: 'surface-plan-v1',
+      seedRefinementRequiredBeforeUiImplementation: true,
+      requireSurfacePlan: true,
+      requireComponentGraph: true,
+      requireViewportMutationPlan: true,
+      requireInteractionStateMatrix: true,
+      requireContentPriorityMap: true,
+      requireTaskFlowNarrative: true,
+      requireSignatureMoveRationale: true,
+      requireStructuredHandoff: true,
+      requireRepoEvidenceAlignment: true,
+      forbidScreenshotDependency: true,
+      handoffFormatVersion: 'ui-handoff-v1',
+      requirePerSurfaceMutationOps: true,
+      forbidUniformSiblingSurfaceTreatment: true,
+      semanticReviewFocus: [
+        'distinctiveness-vs-genericity',
+        'contract-fidelity',
+        'hierarchy-and-task-priority',
+        'component-state-behavior',
+        'cross-viewport-mutation',
+      ],
+    },
+    designExecutionHandoff: {
+      version: 'ui-handoff-v1',
+      location: 'inline-design-intent',
+      status: 'seed-needs-refinement',
+      seedMode: 'structure-first-scaffold',
+      requiresTaskSpecificRefinement: true,
+      primaryExperienceGoal: `Ask the LLM to define the main ${String(primaryDomain || 'product').toLowerCase()} journey in ${projectName} from repo evidence, product context, user goals, and current official documentation where technology choices matter. This scaffold must not prescribe the final visual layout.`,
+      surfacePlan: [
+        {
+          surfaceId: 'agent-defined-primary-experience',
+          role: 'llm-synthesized-from-current-context',
+          goal: `Define the primary UI experience for ${projectName} from the actual product task, audience, data, and repo evidence before coding.`,
+          primaryAction: 'The LLM must choose the first decisive action or reading path and explain why it fits the project.',
+          supportingModules: ['agent-defined-from-current-context'],
+          layoutAntiPatternToAvoid: 'template-default-without-product-rationale',
+          signatureMoveHint: 'Choose and document one project-specific visual, interaction, or content move. Do not inherit it from this scaffold.',
+        },
+        {
+          surfaceId: 'agent-defined-supporting-experience',
+          role: 'llm-synthesized-supporting-context',
+          goal: 'Define supporting, proof, utility, or recovery surfaces from actual user needs instead of cloning generic cards or rails.',
+          primaryAction: 'The LLM must decide what belongs beside, below, hidden behind disclosure, or removed based on task priority.',
+          supportingModules: ['agent-defined-from-current-context'],
+          layoutAntiPatternToAvoid: 'scale-only-responsive-layout',
+          signatureMoveHint: 'Explain how supporting content changes across viewports and why the change improves the experience.',
+        },
+      ],
+      componentGraph: {
+        nodes: [
+          {
+            id: 'agent-defined-primary-experience',
+            role: 'primary-experience-after-synthesis',
+            priority: 'high',
+          },
+          {
+            id: 'agent-defined-supporting-experience',
+            role: 'supporting-experience-after-synthesis',
+            priority: 'medium',
+          },
+        ],
+        edges: [
+          {
+            from: 'agent-defined-primary-experience',
+            to: 'agent-defined-supporting-experience',
+            relationship: 'agent-defined-from-task-priority',
+          },
         ],
       },
-      masking: {
-        requireDynamicContentMasks: true,
-        requireMaskReasonAnnotations: true,
-        allowedDynamicMaskCategories: [
-          'time-based-content',
-          'randomized-content',
-          'live-counters',
-          'streaming-media',
-          'user-specific-personalization',
+      contentPriorityMap: {
+        primary: [
+          'agent-defined-core-task-or-reading-path',
+        ],
+        secondary: [
+          'agent-defined-supporting-context',
+        ],
+        deferred: [
+          'agent-defined-deferred-or-hidden-content',
         ],
       },
-      stability: {
-        maxUnmaskedDiffRatio: 0.005,
-        maxMaskedDiffRatio: 0.02,
-        requireConsistentRenderingEnvironment: true,
+      viewportMutationPlan: {
+        mobile: {
+          primaryOperation: 'agent-defined-mobile-recomposition',
+          requiredSurfaceActions: [
+            'choose-mobile-specific-task-order',
+            'merge-disclose-or-remove-low-priority-content',
+            'adapt-interaction-model-for-touch',
+          ],
+          forbiddenPatterns: [
+            'scale-only-shrink',
+            'desktop-order-preserved-without-priority-shift',
+          ],
+          rationale: inferredKeywords.mutationRules.mobile,
+        },
+        tablet: {
+          primaryOperation: 'agent-defined-tablet-regrouping',
+          requiredSurfaceActions: [
+            'define-medium-width-information-architecture',
+            'avoid-cloning-desktop-by-width-only',
+            'preserve-task-clarity',
+          ],
+          forbiddenPatterns: [
+            'desktop-layout-reduced-by-width-only',
+            'uniform-module-grid-without-role-change',
+          ],
+          rationale: inferredKeywords.mutationRules.tablet,
+        },
+        desktop: {
+          primaryOperation: 'agent-defined-desktop-composition',
+          requiredSurfaceActions: [
+            'use-space-to-improve-hierarchy',
+            'define-scan-pattern-and-action-priority',
+            'avoid-equalizing-unrelated-content',
+          ],
+          forbiddenPatterns: [
+            'template-shell-without-product-rationale',
+            'interchangeable-dashboard-or-landing-chrome',
+          ],
+          rationale: inferredKeywords.mutationRules.desktop,
+        },
       },
-      semanticEscalation: {
-        requireMeaningfulDiffForEscalation: true,
-        escalateWhenViewportCoverageIncomplete: true,
-        skipSemanticJudgeWhenDeterministicClean: true,
-        meaningfulDiffRatioThreshold: 0.01,
+      interactionStateMatrix: [
+        {
+          componentId: 'primary-action-control',
+          states: ['default', 'hover', 'focus', 'loading', 'success', 'error'],
+          notes: 'Refine these states with project-specific feedback language and visual treatment, but keep them legible, decisive, and consistent across all supported viewports.',
+        },
+        {
+          componentId: 'primary-content-module',
+          states: ['default', 'focus', 'expanded', 'loading', 'error'],
+          notes: 'Refine this module so it preserves hierarchy and progressive disclosure without collapsing into anonymous cards or safe default dashboard panels.',
+        },
+      ],
+      taskFlowNarrative: [
+        `Entry: the LLM must define how ${projectName} starts the user journey from real product evidence instead of a generic opening pattern.`,
+        'Decision: the LLM must define hierarchy, proof, state language, and interaction behavior from the actual task.',
+        'Resolution: the LLM must define feedback, recovery, and next-useful-action behavior without defaulting to leftover template chrome.',
+      ],
+      signatureMoveRationale: 'The LLM must choose the project-specific visual, motion, typographic, compositional, or interaction move after reading current context and explain why a generic fallback would weaken the product.',
+      implementationGuardrails: {
+        requireBuildFromHandoff: true,
+        requireGapNotesBeforeFallback: true,
+        forbidGenericLayoutFallbackWithoutReason: true,
       },
-      artifactContract: {
-        requireMachineReadableDiffBundle: true,
-        requireViewportResults: true,
-        mergeDeterministicAndSemanticVerdicts: true,
+    },
+    reviewRubric: {
+      version: 'ui-rubric-v1',
+      genericityAutoFail: true,
+      dimensions: [
+        {
+          key: 'distinctiveness',
+          blockingByDefault: true,
+          question: 'Does the UI feel authored and project-specific rather than like a default framework or template kit?',
+        },
+        {
+          key: 'contractFidelity',
+          blockingByDefault: true,
+          question: 'Does the changed UI still follow the explicit design contract, interaction priorities, and accessibility boundaries?',
+        },
+        {
+          key: 'visualConsistency',
+          blockingByDefault: false,
+          question: 'Do typography, spacing, color usage, and component behaviors still feel like one system?',
+        },
+        {
+          key: 'heuristicUxQuality',
+          blockingByDefault: false,
+          question: 'Does the UI preserve task clarity, feedback quality, and user confidence in the touched flows?',
+        },
+        {
+          key: 'motionDiscipline',
+          blockingByDefault: false,
+          question: 'If motion is present, does it stay purposeful, performant, reduced-motion-safe, and consistent with the product tone?',
+        },
+      ],
+      genericitySignals: [
+        'offline-prescribed-style-used-as-final-direction',
+        'unresearched-library-or-framework-choice',
+        'default-component-kit-treatment-without-product-rationale',
+        'scale-only-responsive-layout',
+        'template-shell-without-product-rationale',
+        'inaccessible-or-decorative-motion',
+      ],
+      validBoldSignals: [
+        'context-derived-visual-direction',
+        'official-docs-backed-library-choice',
+        'responsive-recomposition-by-task-priority',
+        'purposeful-motion-with-reduced-motion-path',
+        'documented-design-rationale-before-code',
+        'clean-component-and-token-architecture',
+      ],
+      reportingRules: {
+        mustExplainGenericity: true,
+        mustSeparateTasteFromFailure: true,
+        contractFidelityOverridesPersonalTaste: true,
       },
     },
     contextHygiene: {
@@ -380,7 +427,7 @@ function buildDesignIntentContractObject({
         'current-repo-evidence',
         'current-user-brief',
         'current-project-docs',
-        'explicitly-approved-reference-systems',
+        'explicitly-approved-current-task-constraints',
       ],
       taintedSources: [
         'prior-chat-visual-memory',
@@ -391,7 +438,7 @@ function buildDesignIntentContractObject({
       repoEvidenceOverridesMemory: true,
       requireExplicitContinuityApproval: true,
       forbidCarryoverWhenUnapproved: true,
-      approvedReferenceUsage: 'Adapt reasoning and constraints from approved references without copying the surface 1:1.',
+      approvedExternalConstraintUsage: 'Convert explicit user-supplied external constraints into current-project rules without comparing against or imitating the source surface.',
       driftSignals: [
         'palette-reused-without-brief-support',
         'motion-signature-reused-without-approval',
@@ -403,15 +450,17 @@ function buildDesignIntentContractObject({
       '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.',
-      'Motion may add character, memorability, and continuity when it improves the product experience, but it must stay purposeful, performant, and optional for reduced-motion users.',
-      'At least one surface, compositional move, typographic decision, or motion motif should be recognizable at a glance.',
+      'Modern libraries and interaction patterns may be used when the LLM verifies they fit the project and current official docs.',
+      'Motion may be rich and memorable when it improves the product experience, but it must stay purposeful, performant, and optional for reduced-motion users.',
+      'At least one visual, interaction, content, or motion decision must be recognizable at a glance and justified from context.',
     ],
     forbiddenPatterns: [
-      'generic-saas-hero',
-      'copycat-brand-system',
-      'unjustified-default-gradients',
-      'placeholder-design-language',
+      'offline-prescribed-style-used-as-final-direction',
+      'unresearched-library-or-framework-choice',
+      'default-component-kit-treatment-without-product-rationale',
       'scale-only-responsive-layout',
+      'template-shell-without-product-rationale',
+      'single-safe-typographic-family-without-role-contrast-or-rationale',
     ],
     validationHints: {
       rejectArbitraryHexOnlyPalette: true,
@@ -424,7 +473,11 @@ function buildDesignIntentContractObject({
       requireStateMorphology: true,
       requireAccessibilitySplit: true,
       requireWcagHardFloor: true,
-      requireHybridVisualQaPolicy: true,
+      requireStructuredDesignExecutionPolicy: true,
+      requireStructuredDesignHandoff: true,
+      requireReviewRubric: true,
+      requireGenericityExplanation: true,
+      genericityAutoFail: true,
       requireSignatureMove: true,
       rejectTemplateNeutralLayout: true,
     },
@@ -474,11 +527,11 @@ export function validateDesignIntentContract(designIntentContract) {
   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 (!String(designIntentContract.mathSystems.typographyScaleRatio || '').trim()) {
+      validationErrors.push('designIntent.mathSystems.typographyScaleRatio must describe the chosen or pending type scale decision.');
     }
-    if (!Number.isInteger(designIntentContract.mathSystems.baseGridUnit) || designIntentContract.mathSystems.baseGridUnit <= 0) {
-      validationErrors.push('designIntent.mathSystems.baseGridUnit must be a positive integer.');
+    if (!String(designIntentContract.mathSystems.baseGridUnit || '').trim()) {
+      validationErrors.push('designIntent.mathSystems.baseGridUnit must describe the chosen or pending spacing grid decision.');
     }
   }
 
@@ -540,6 +593,16 @@ export function validateDesignIntentContract(designIntentContract) {
     if (designIntentContract.colorTruth.allowHexDerivatives !== true) {
       validationErrors.push('designIntent.colorTruth.allowHexDerivatives must equal true.');
     }
+    if (!String(designIntentContract.colorTruth.intent || '').trim()) {
+      validationErrors.push('designIntent.colorTruth.intent must be a non-empty string.');
+    }
+    const paletteRoles = designIntentContract.colorTruth.paletteRoles;
+    if (!Array.isArray(paletteRoles) || paletteRoles.length < 1) {
+      validationErrors.push('designIntent.colorTruth.paletteRoles must define or request agent-defined semantic palette roles.');
+    }
+    if (designIntentContract.colorTruth.rolesMustBeAgentDefined !== true) {
+      validationErrors.push('designIntent.colorTruth.rolesMustBeAgentDefined must equal true.');
+    }
   }
 
   if (!designIntentContract.crossViewportAdaptation || typeof designIntentContract.crossViewportAdaptation !== 'object') {
@@ -665,135 +728,175 @@ export function validateDesignIntentContract(designIntentContract) {
     if (!Array.isArray(designIntentContract.contextHygiene.taintedSources) || designIntentContract.contextHygiene.taintedSources.length < 3) {
       validationErrors.push('designIntent.contextHygiene.taintedSources must list tainted carryover sources.');
     }
-    if (!String(designIntentContract.contextHygiene.approvedReferenceUsage || '').trim()) {
-      validationErrors.push('designIntent.contextHygiene.approvedReferenceUsage must be a non-empty string.');
+    if (!String(designIntentContract.contextHygiene.approvedExternalConstraintUsage || '').trim()) {
+      validationErrors.push('designIntent.contextHygiene.approvedExternalConstraintUsage must be a non-empty string.');
+    }
+  }
+
+  if (!designIntentContract.designExecutionPolicy || typeof designIntentContract.designExecutionPolicy !== 'object') {
+    validationErrors.push('designIntent.designExecutionPolicy must exist.');
+  } else {
+    if (designIntentContract.designExecutionPolicy.representationStrategy !== 'surface-plan-v1') {
+      validationErrors.push('designIntent.designExecutionPolicy.representationStrategy must equal "surface-plan-v1".');
+    }
+    for (const requiredFlagName of [
+      'requireSurfacePlan',
+      'requireComponentGraph',
+      'requireViewportMutationPlan',
+      'requireInteractionStateMatrix',
+      'requireContentPriorityMap',
+      'requireTaskFlowNarrative',
+      'requireSignatureMoveRationale',
+      'requireStructuredHandoff',
+      'requireRepoEvidenceAlignment',
+      'forbidScreenshotDependency',
+      'requirePerSurfaceMutationOps',
+      'forbidUniformSiblingSurfaceTreatment',
+    ]) {
+      if (designIntentContract.designExecutionPolicy[requiredFlagName] !== true) {
+        validationErrors.push(`designIntent.designExecutionPolicy.${requiredFlagName} must equal true.`);
+      }
+    }
+    if (designIntentContract.designExecutionPolicy.handoffFormatVersion !== 'ui-handoff-v1') {
+      validationErrors.push('designIntent.designExecutionPolicy.handoffFormatVersion must equal "ui-handoff-v1".');
+    }
+    if (
+      !Array.isArray(designIntentContract.designExecutionPolicy.semanticReviewFocus)
+      || designIntentContract.designExecutionPolicy.semanticReviewFocus.length < 4
+    ) {
+      validationErrors.push('designIntent.designExecutionPolicy.semanticReviewFocus must list the required review dimensions.');
     }
   }
 
-  if (!designIntentContract.visualQaPolicy || typeof designIntentContract.visualQaPolicy !== 'object') {
-    validationErrors.push('designIntent.visualQaPolicy must exist.');
+  if (!designIntentContract.designExecutionHandoff || typeof designIntentContract.designExecutionHandoff !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff must exist.');
   } else {
-    if (designIntentContract.visualQaPolicy.deterministicFirst !== true) {
-      validationErrors.push('designIntent.visualQaPolicy.deterministicFirst must equal true.');
+    if (designIntentContract.designExecutionHandoff.version !== 'ui-handoff-v1') {
+      validationErrors.push('designIntent.designExecutionHandoff.version must equal "ui-handoff-v1".');
     }
-    if (designIntentContract.visualQaPolicy.baselineStrategy !== 'deterministic-screenshots') {
-      validationErrors.push('designIntent.visualQaPolicy.baselineStrategy must equal "deterministic-screenshots".');
+    if (designIntentContract.designExecutionHandoff.seedMode !== 'structure-first-scaffold') {
+      validationErrors.push('designIntent.designExecutionHandoff.seedMode must equal "structure-first-scaffold".');
     }
-    if (designIntentContract.visualQaPolicy.reportVersion !== 'hybrid-visual-diff-v1') {
-      validationErrors.push('designIntent.visualQaPolicy.reportVersion must equal "hybrid-visual-diff-v1".');
+    if (designIntentContract.designExecutionHandoff.requiresTaskSpecificRefinement !== true) {
+      validationErrors.push('designIntent.designExecutionHandoff.requiresTaskSpecificRefinement must equal true.');
     }
-    if (!Array.isArray(designIntentContract.visualQaPolicy.requiredViewports) || designIntentContract.visualQaPolicy.requiredViewports.join('|') !== 'mobile|tablet|desktop') {
-      validationErrors.push('designIntent.visualQaPolicy.requiredViewports must equal ["mobile","tablet","desktop"].');
+    if (!String(designIntentContract.designExecutionHandoff.primaryExperienceGoal || '').trim()) {
+      validationErrors.push('designIntent.designExecutionHandoff.primaryExperienceGoal must be a non-empty string.');
     }
-
-    const capturePlan = designIntentContract.visualQaPolicy.capturePlan;
-    if (!capturePlan || typeof capturePlan !== 'object') {
-      validationErrors.push('designIntent.visualQaPolicy.capturePlan must exist.');
+    if (!Array.isArray(designIntentContract.designExecutionHandoff.surfacePlan) || designIntentContract.designExecutionHandoff.surfacePlan.length < 1) {
+      validationErrors.push('designIntent.designExecutionHandoff.surfacePlan must define at least one planned surface.');
+    }
+    const componentGraph = designIntentContract.designExecutionHandoff.componentGraph;
+    if (!componentGraph || typeof componentGraph !== 'object') {
+      validationErrors.push('designIntent.designExecutionHandoff.componentGraph must exist.');
     } else {
-      if (capturePlan.requireAboveFoldCapture !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.requireAboveFoldCapture must equal true.');
-      }
-      if (capturePlan.requireFullPageCapture !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.requireFullPageCapture must equal true.');
-      }
-      if (capturePlan.requireSectionCapturesForLongPages !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.requireSectionCapturesForLongPages must equal true.');
+      if (!Array.isArray(componentGraph.nodes) || componentGraph.nodes.length < 2) {
+        validationErrors.push('designIntent.designExecutionHandoff.componentGraph.nodes must list the primary execution nodes.');
       }
-      if (capturePlan.longPageStrategy !== 'anchor-plus-tiles') {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.longPageStrategy must equal "anchor-plus-tiles".');
-      }
-      if (
-        typeof capturePlan.minimumSectionCaptureCount !== 'number'
-        || capturePlan.minimumSectionCaptureCount < 3
-      ) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.minimumSectionCaptureCount must be a number greater than or equal to 3.');
-      }
-      if (
-        typeof capturePlan.maxViewportHeightsPerTile !== 'number'
-        || capturePlan.maxViewportHeightsPerTile < 2
-        || capturePlan.maxViewportHeightsPerTile > 6
-      ) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.maxViewportHeightsPerTile must be a number between 2 and 6.');
-      }
-      if (
-        typeof capturePlan.tileOverlapRatio !== 'number'
-        || capturePlan.tileOverlapRatio <= 0
-        || capturePlan.tileOverlapRatio >= 0.5
-      ) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.tileOverlapRatio must be a number between 0 and 0.5.');
-      }
-      if (!Array.isArray(capturePlan.requiredSectionTypes) || capturePlan.requiredSectionTypes.length < 3) {
-        validationErrors.push('designIntent.visualQaPolicy.capturePlan.requiredSectionTypes must list the required section capture types.');
+      if (!Array.isArray(componentGraph.edges) || componentGraph.edges.length < 1) {
+        validationErrors.push('designIntent.designExecutionHandoff.componentGraph.edges must define relationships between UI nodes.');
       }
     }
-
-    const maskingPolicy = designIntentContract.visualQaPolicy.masking;
-    if (!maskingPolicy || typeof maskingPolicy !== 'object') {
-      validationErrors.push('designIntent.visualQaPolicy.masking must exist.');
+    const contentPriorityMap = designIntentContract.designExecutionHandoff.contentPriorityMap;
+    if (!contentPriorityMap || typeof contentPriorityMap !== 'object') {
+      validationErrors.push('designIntent.designExecutionHandoff.contentPriorityMap must exist.');
     } else {
-      if (maskingPolicy.requireDynamicContentMasks !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.masking.requireDynamicContentMasks must equal true.');
-      }
-      if (maskingPolicy.requireMaskReasonAnnotations !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.masking.requireMaskReasonAnnotations must equal true.');
-      }
-      if (!Array.isArray(maskingPolicy.allowedDynamicMaskCategories) || maskingPolicy.allowedDynamicMaskCategories.length < 4) {
-        validationErrors.push('designIntent.visualQaPolicy.masking.allowedDynamicMaskCategories must list the approved masking categories.');
+      for (const priorityBucket of ['primary', 'secondary', 'deferred']) {
+        if (!Array.isArray(contentPriorityMap[priorityBucket]) || contentPriorityMap[priorityBucket].length < 1) {
+          validationErrors.push(`designIntent.designExecutionHandoff.contentPriorityMap.${priorityBucket} must contain at least one item.`);
+        }
       }
     }
-
-    const stabilityPolicy = designIntentContract.visualQaPolicy.stability;
-    if (!stabilityPolicy || typeof stabilityPolicy !== 'object') {
-      validationErrors.push('designIntent.visualQaPolicy.stability must exist.');
+    const viewportMutationPlan = designIntentContract.designExecutionHandoff.viewportMutationPlan;
+    if (!viewportMutationPlan || typeof viewportMutationPlan !== 'object') {
+      validationErrors.push('designIntent.designExecutionHandoff.viewportMutationPlan must exist.');
     } else {
-      if (typeof stabilityPolicy.maxUnmaskedDiffRatio !== 'number' || stabilityPolicy.maxUnmaskedDiffRatio <= 0 || stabilityPolicy.maxUnmaskedDiffRatio >= 0.1) {
-        validationErrors.push('designIntent.visualQaPolicy.stability.maxUnmaskedDiffRatio must be a number between 0 and 0.1.');
-      }
-      if (typeof stabilityPolicy.maxMaskedDiffRatio !== 'number' || stabilityPolicy.maxMaskedDiffRatio <= 0 || stabilityPolicy.maxMaskedDiffRatio >= 0.1) {
-        validationErrors.push('designIntent.visualQaPolicy.stability.maxMaskedDiffRatio must be a number between 0 and 0.1.');
-      }
-      if (stabilityPolicy.maxMaskedDiffRatio < stabilityPolicy.maxUnmaskedDiffRatio) {
-        validationErrors.push('designIntent.visualQaPolicy.stability.maxMaskedDiffRatio must be greater than or equal to maxUnmaskedDiffRatio.');
-      }
-      if (stabilityPolicy.requireConsistentRenderingEnvironment !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.stability.requireConsistentRenderingEnvironment must equal true.');
+      for (const viewportKey of ['mobile', 'tablet', 'desktop']) {
+        const viewportPlan = viewportMutationPlan[viewportKey];
+        if (!viewportPlan || typeof viewportPlan !== 'object') {
+          validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey} must be an object.`);
+          continue;
+        }
+        if (!String(viewportPlan.primaryOperation || '').trim()) {
+          validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.primaryOperation must be a non-empty string.`);
+        }
+        if (!Array.isArray(viewportPlan.requiredSurfaceActions) || viewportPlan.requiredSurfaceActions.length < 2) {
+          validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.requiredSurfaceActions must contain at least two actions.`);
+        }
+        if (!Array.isArray(viewportPlan.forbiddenPatterns) || viewportPlan.forbiddenPatterns.length < 1) {
+          validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.forbiddenPatterns must contain at least one anti-pattern.`);
+        }
+        if (!String(viewportPlan.rationale || '').trim()) {
+          validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.rationale must be a non-empty string.`);
+        }
       }
     }
-
-    const semanticEscalationPolicy = designIntentContract.visualQaPolicy.semanticEscalation;
-    if (!semanticEscalationPolicy || typeof semanticEscalationPolicy !== 'object') {
-      validationErrors.push('designIntent.visualQaPolicy.semanticEscalation must exist.');
+    if (!Array.isArray(designIntentContract.designExecutionHandoff.interactionStateMatrix) || designIntentContract.designExecutionHandoff.interactionStateMatrix.length < 1) {
+      validationErrors.push('designIntent.designExecutionHandoff.interactionStateMatrix must list key component state expectations.');
+    }
+    if (!Array.isArray(designIntentContract.designExecutionHandoff.taskFlowNarrative) || designIntentContract.designExecutionHandoff.taskFlowNarrative.length < 2) {
+      validationErrors.push('designIntent.designExecutionHandoff.taskFlowNarrative must describe the key UI task flow in sequence.');
+    }
+    if (!String(designIntentContract.designExecutionHandoff.signatureMoveRationale || '').trim()) {
+      validationErrors.push('designIntent.designExecutionHandoff.signatureMoveRationale must explain the chosen authored move.');
+    }
+    const implementationGuardrails = designIntentContract.designExecutionHandoff.implementationGuardrails;
+    if (!implementationGuardrails || typeof implementationGuardrails !== 'object') {
+      validationErrors.push('designIntent.designExecutionHandoff.implementationGuardrails must exist.');
     } else {
-      if (semanticEscalationPolicy.requireMeaningfulDiffForEscalation !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.semanticEscalation.requireMeaningfulDiffForEscalation must equal true.');
-      }
-      if (semanticEscalationPolicy.escalateWhenViewportCoverageIncomplete !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.semanticEscalation.escalateWhenViewportCoverageIncomplete must equal true.');
-      }
-      if (semanticEscalationPolicy.skipSemanticJudgeWhenDeterministicClean !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.semanticEscalation.skipSemanticJudgeWhenDeterministicClean must equal true.');
-      }
-      if (
-        typeof semanticEscalationPolicy.meaningfulDiffRatioThreshold !== 'number'
-        || semanticEscalationPolicy.meaningfulDiffRatioThreshold <= 0
-        || semanticEscalationPolicy.meaningfulDiffRatioThreshold >= 0.2
-      ) {
-        validationErrors.push('designIntent.visualQaPolicy.semanticEscalation.meaningfulDiffRatioThreshold must be a number between 0 and 0.2.');
+      for (const requiredFlagName of [
+        'requireBuildFromHandoff',
+        'requireGapNotesBeforeFallback',
+        'forbidGenericLayoutFallbackWithoutReason',
+      ]) {
+        if (implementationGuardrails[requiredFlagName] !== true) {
+          validationErrors.push(`designIntent.designExecutionHandoff.implementationGuardrails.${requiredFlagName} must equal true.`);
+        }
       }
     }
+  }
 
-    const artifactContract = designIntentContract.visualQaPolicy.artifactContract;
-    if (!artifactContract || typeof artifactContract !== 'object') {
-      validationErrors.push('designIntent.visualQaPolicy.artifactContract must exist.');
+  if (!designIntentContract.reviewRubric || typeof designIntentContract.reviewRubric !== 'object') {
+    validationErrors.push('designIntent.reviewRubric must exist.');
+  } else {
+    if (designIntentContract.reviewRubric.version !== 'ui-rubric-v1') {
+      validationErrors.push('designIntent.reviewRubric.version must equal "ui-rubric-v1".');
+    }
+    if (designIntentContract.reviewRubric.genericityAutoFail !== true) {
+      validationErrors.push('designIntent.reviewRubric.genericityAutoFail must equal true.');
+    }
+    if (!Array.isArray(designIntentContract.reviewRubric.dimensions) || designIntentContract.reviewRubric.dimensions.length < 5) {
+      validationErrors.push('designIntent.reviewRubric.dimensions must define the required rubric dimensions.');
     } else {
-      if (artifactContract.requireMachineReadableDiffBundle !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.artifactContract.requireMachineReadableDiffBundle must equal true.');
-      }
-      if (artifactContract.requireViewportResults !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.artifactContract.requireViewportResults must equal true.');
+      for (const requiredRubricKey of [
+        'distinctiveness',
+        'contractFidelity',
+        'visualConsistency',
+        'heuristicUxQuality',
+        'motionDiscipline',
+      ]) {
+        if (!designIntentContract.reviewRubric.dimensions.some((dimension) => dimension?.key === requiredRubricKey)) {
+          validationErrors.push(`designIntent.reviewRubric.dimensions is missing "${requiredRubricKey}".`);
+        }
       }
-      if (artifactContract.mergeDeterministicAndSemanticVerdicts !== true) {
-        validationErrors.push('designIntent.visualQaPolicy.artifactContract.mergeDeterministicAndSemanticVerdicts must equal true.');
+    }
+    if (!Array.isArray(designIntentContract.reviewRubric.genericitySignals) || designIntentContract.reviewRubric.genericitySignals.length < 3) {
+      validationErrors.push('designIntent.reviewRubric.genericitySignals must list common genericity drift signals.');
+    }
+    if (!Array.isArray(designIntentContract.reviewRubric.validBoldSignals) || designIntentContract.reviewRubric.validBoldSignals.length < 3) {
+      validationErrors.push('designIntent.reviewRubric.validBoldSignals must list legitimate authored signals.');
+    }
+    if (!designIntentContract.reviewRubric.reportingRules || typeof designIntentContract.reviewRubric.reportingRules !== 'object') {
+      validationErrors.push('designIntent.reviewRubric.reportingRules must exist.');
+    } else {
+      for (const requiredFlagName of [
+        'mustExplainGenericity',
+        'mustSeparateTasteFromFailure',
+        'contractFidelityOverridesPersonalTaste',
+      ]) {
+        if (designIntentContract.reviewRubric.reportingRules[requiredFlagName] !== true) {
+          validationErrors.push(`designIntent.reviewRubric.reportingRules.${requiredFlagName} must equal true.`);
+        }
       }
     }
   }
@@ -808,6 +911,10 @@ export function validateDesignIntentContract(designIntentContract) {
     }
   }
 
+  if (!Array.isArray(designIntentContract.forbiddenPatterns) || designIntentContract.forbiddenPatterns.length < 4) {
+    validationErrors.push('designIntent.forbiddenPatterns must list concrete anti-generic patterns.');
+  }
+
   return validationErrors;
 }
 
@@ -817,7 +924,6 @@ export function buildDesignIntentSeedFromSignals({
   primaryDomain,
   features = [],
   initContext,
-  architectureRecommendation = null,
   status = 'seed-needs-design-synthesis',
   supplementalFields = {},
 }) {
@@ -827,7 +933,6 @@ export function buildDesignIntentSeedFromSignals({
     primaryDomain,
     features,
     initContext,
-    architectureRecommendation,
     status,
     supplementalFields,
   });
@@ -843,7 +948,6 @@ export function buildDesignIntentSeedFromSignals({
 export function buildDesignIntentSeed({
   discoveryAnswers,
   initContext,
-  architectureRecommendation,
 }) {
   return buildDesignIntentSeedFromSignals({
     projectName: discoveryAnswers.projectName,
@@ -851,7 +955,6 @@ export function buildDesignIntentSeed({
     primaryDomain: discoveryAnswers.primaryDomain,
     features: discoveryAnswers.features,
     initContext,
-    architectureRecommendation,
     status: 'seed-needs-design-synthesis',
   });
 }