@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.19

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

@@ -29,174 +29,58 @@ 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 normalizedDomain = String(primaryDomain || '').trim().toLowerCase();
+  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';
+  const isMobileLikeSurface = normalizedDomain.includes('mobile');
 
   return {
-    designPhilosophy: 'Project-specific clarity with one authored tension and one memorable visual bet.',
-    brandAdjectives: ['clear', 'human', 'distinct'],
-    antiAdjectives: ['generic', 'template-like', 'trend-chasing'],
+    designPhilosophy: `Use ${evidenceSourceLabel} to synthesize a project-specific design system for ${projectName || 'this project'}. Treat this seed as structural scaffolding that must be refined before UI implementation, not as final art direction.`,
+    brandAdjectives: ['project-specific', 'intentional', 'evidence-led'],
+    antiAdjectives: ['template-neutral', 'copycat', 'unjustified-defaults'],
     typographyScaleRatio: '1.200',
     baseGridUnit: 8,
-    densityMode: 'balanced-authored',
-    colorIntent: 'Use a restrained perceptual palette with one deliberate accent budget instead of interchangeable template colors.',
+    spacingPattern: isMobileLikeSurface ? 'mobile-first-single-axis' : 'adaptive-task-priority',
+    densityMode: isMobileLikeSurface ? 'touch-priority' : 'adaptive-task-priority',
+    colorIntent: `Define palette roles from ${projectContextLabel} and refine them with repo evidence. Treat the listed palette roles as minimum semantic categories, not final visual choices.`,
+    paletteRoles: ['base', 'surface', 'text', 'muted', 'accent', 'border', 'focus', 'success', 'warning', 'danger'],
     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.',
+      'Derive one memorable signature move from the product task, current repo evidence, and the active brief before locking the layout language.',
+      'Use task priority, hierarchy, and surface relationships to replace template-neutral hero or card-grid defaults.',
+      'Document why the final visual move belongs to this project and what generic fallback 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 motion to clarify causality, hierarchy, state feedback, and perceived product quality. The final motion tone must be refined from repo evidence and the active brief, not inherited from this seed alone.',
+    motionChoreography: 'Keep motion purposeful, reduced-motion-safe, and tied to state or surface changes. Any signature choreography must be justified in docs/DESIGN.md before it becomes part of the system.',
     motionDurations: {
       desktop: 180,
       mobile: 240,
     },
     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: 'Simplify the primary task surface, keep decisive actions in easy reach, and move supporting context behind explicit disclosure when space gets tight.',
+      tablet: 'Preserve task continuity while compressing tertiary chrome and keeping priority boundaries obvious across shared surfaces.',
+      desktop: 'Expose the richest version of the task flow and supporting context without defaulting to symmetrical template composition.',
     },
     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: 'Recompose the flow around the first decisive action, collapse secondary navigation into explicit overlays or sheets, and re-rank supporting context below the primary task.',
+      tablet: 'Preserve task continuity with fewer simultaneous surfaces, condensed chrome, and explicit boundaries between primary, supporting, and deferred content.',
+      desktop: 'Expose the fullest version of the task flow, supporting context, and navigation system without falling back to interchangeable dashboard or hero defaults.',
     },
   };
 }
@@ -207,27 +91,26 @@ 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,
@@ -239,6 +122,8 @@ function buildDesignIntentContractObject({
     brandAdjectives: inferredKeywords.brandAdjectives,
     antiAdjectives: inferredKeywords.antiAdjectives,
     visualDirection: {
+      seedMode: 'scaffold-only',
+      requiresProjectSpecificSynthesis: true,
       trendStance: 'trend-aware-not-trend-chasing',
       distinctiveMoves: inferredKeywords.distinctiveMoves,
       copiedReferenceAllowed: false,
@@ -246,8 +131,9 @@ function buildDesignIntentContractObject({
     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 +166,9 @@ function buildDesignIntentContractObject({
       format: 'OKLCH',
       allowHexDerivatives: true,
       requirePerceptualLightnessCurve: true,
-      paletteRoles: ['base', 'surface', 'accent'],
+      paletteRoles: inferredKeywords.paletteRoles,
+      rolePolicy: 'minimum-semantic-scaffold',
+      rolesAreMinimumScaffold: true,
       intent: inferredKeywords.colorIntent,
     },
     crossViewportAdaptation: {
@@ -294,6 +182,7 @@ function buildDesignIntentContractObject({
       choreography: inferredKeywords.motionChoreography,
       desktopDurationMs: inferredKeywords.motionDurations.desktop,
       mobileDurationMs: inferredKeywords.motionDurations.mobile,
+      seedToneLocked: false,
       respectReducedMotion: true,
       preferTransformAndOpacity: true,
       avoidDecorativeMotionForItsOwnSake: true,
@@ -301,6 +190,7 @@ function buildDesignIntentContractObject({
     componentMorphology: {
       requireStateBehaviorMatrix: true,
       preserveIdentityAcrossViewports: true,
+      seedBehaviorsRequireRefinement: true,
       stateKeys: ['default', 'hover', 'focus', 'active', 'disabled', 'loading', 'error'],
       viewportBehavior: inferredKeywords.componentMorphology,
     },
@@ -327,51 +217,177 @@ 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',
+      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: `Refine the main ${String(primaryDomain || 'product').toLowerCase()} journey in ${projectName} so the first decisive action, supporting context, and signature move come from repo evidence and the active brief rather than scaffold defaults.`,
+      surfacePlan: [
+        {
+          surfaceId: 'primary-entry-surface',
+          role: 'primary-task-entry',
+          goal: `Map the first meaningful task in ${projectName} and replace generic hero filler with task-first hierarchy justified by repo evidence and the active brief.`,
+          primaryAction: 'Define the first decisive action or decision point explicitly during refinement instead of inheriting placeholder CTA language.',
+          supportingModules: ['context', 'proof', 'navigation'],
+          signatureMoveHint: 'Document one project-specific signature move for the primary surface and explain which generic fallback it intentionally rejects.',
+        },
+        {
+          surfaceId: 'supporting-proof-surface',
+          role: 'trust-and-context',
+          goal: 'Define how proof, explanation, or operational context supports the main task without turning the layout into a template-neutral secondary rail.',
+          primaryAction: 'Clarify what supporting proof or status belongs near the main task once the product-specific flow is confirmed.',
+          supportingModules: ['status', 'metadata', 'secondary-actions'],
+          signatureMoveHint: 'Explain how this supporting surface reinforces the primary task without competing for dominance or collapsing into generic chrome.',
+        },
+      ],
+      componentGraph: {
+        nodes: [
+          {
+            id: 'primary-action-surface',
+            role: 'task-driver',
+            priority: 'high',
+          },
+          {
+            id: 'supporting-context-rail',
+            role: 'context-support',
+            priority: 'medium',
+          },
+          {
+            id: 'feedback-status-module',
+            role: 'feedback-and-proof',
+            priority: 'medium',
+          },
+        ],
+        edges: [
+          {
+            from: 'primary-action-surface',
+            to: 'supporting-context-rail',
+            relationship: 'context-support',
+          },
+          {
+            from: 'primary-action-surface',
+            to: 'feedback-status-module',
+            relationship: 'state-feedback',
+          },
         ],
       },
-      masking: {
-        requireDynamicContentMasks: true,
-        requireMaskReasonAnnotations: true,
-        allowedDynamicMaskCategories: [
-          'time-based-content',
-          'randomized-content',
-          'live-counters',
-          'streaming-media',
-          'user-specific-personalization',
+      contentPriorityMap: {
+        primary: [
+          'core-task-entry',
+          'primary-status-or-value-message',
+          'decisive-action-labeling',
+        ],
+        secondary: [
+          'supporting-proof',
+          'navigation-context',
+          'secondary-actions',
+        ],
+        deferred: [
+          'deep-explanation',
+          'tertiary-metadata',
+          'low-priority-decoration',
         ],
       },
-      stability: {
-        maxUnmaskedDiffRatio: 0.005,
-        maxMaskedDiffRatio: 0.02,
-        requireConsistentRenderingEnvironment: true,
+      viewportMutationPlan: {
+        mobile: inferredKeywords.mutationRules.mobile,
+        tablet: inferredKeywords.mutationRules.tablet,
+        desktop: 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: refine how ${projectName} establishes the first meaningful action using current task evidence instead of generic product-marketing framing.`,
+        'Decision: define the hierarchy, proof, and state language that help the user choose the next step without defaulting to generic card-grid or hero habits.',
+        'Resolution: specify the feedback, recovery path, and next useful action so progress remains visible without hiding behind decorative confirmation states.',
+      ],
+      signatureMoveRationale: 'Explain which project-specific surface, motion, typographic, or compositional move anchors the system and 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',
+      dimensions: [
+        {
+          key: 'distinctiveness',
+          blockingByDefault: false,
+          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: [
+        'safe-centered-hero-without-product-rationale',
+        'balanced-card-grid-without-priority-shift',
+        'default-framework-button-and-input-treatment',
+        'trend-gradient-without-structural-role',
+        'interchangeable-dashboard-chrome',
+      ],
+      validBoldSignals: [
+        'one-clear-signature-move',
+        'project-specific-layout-tension',
+        'purposeful-motion-as-identity',
+        'distinct-typographic-hierarchy',
+        'non-template-task-priority',
+      ],
+      reportingRules: {
+        mustExplainGenericity: true,
+        mustSeparateTasteFromFailure: true,
+        contractFidelityOverridesPersonalTaste: true,
       },
     },
     contextHygiene: {
@@ -424,7 +440,10 @@ function buildDesignIntentContractObject({
       requireStateMorphology: true,
       requireAccessibilitySplit: true,
       requireWcagHardFloor: true,
-      requireHybridVisualQaPolicy: true,
+      requireStructuredDesignExecutionPolicy: true,
+      requireStructuredDesignHandoff: true,
+      requireReviewRubric: true,
+      requireGenericityExplanation: true,
       requireSignatureMove: true,
       rejectTemplateNeutralLayout: true,
     },
@@ -540,6 +559,19 @@ 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 < 4) {
+      validationErrors.push('designIntent.colorTruth.paletteRoles must define the minimum semantic palette roles.');
+    } else {
+      for (const requiredPaletteRole of ['base', 'surface', 'text', 'accent']) {
+        if (!paletteRoles.includes(requiredPaletteRole)) {
+          validationErrors.push(`designIntent.colorTruth.paletteRoles is missing "${requiredPaletteRole}".`);
+        }
+      }
+    }
   }
 
   if (!designIntentContract.crossViewportAdaptation || typeof designIntentContract.crossViewportAdaptation !== 'object') {
@@ -670,130 +702,151 @@ export function validateDesignIntentContract(designIntentContract) {
     }
   }
 
-  if (!designIntentContract.visualQaPolicy || typeof designIntentContract.visualQaPolicy !== 'object') {
-    validationErrors.push('designIntent.visualQaPolicy must exist.');
+  if (!designIntentContract.designExecutionPolicy || typeof designIntentContract.designExecutionPolicy !== 'object') {
+    validationErrors.push('designIntent.designExecutionPolicy must exist.');
   } else {
-    if (designIntentContract.visualQaPolicy.deterministicFirst !== true) {
-      validationErrors.push('designIntent.visualQaPolicy.deterministicFirst must equal true.');
+    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',
+    ]) {
+      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.baselineStrategy !== 'deterministic-screenshots') {
-      validationErrors.push('designIntent.visualQaPolicy.baselineStrategy must equal "deterministic-screenshots".');
+  }
+
+  if (!designIntentContract.designExecutionHandoff || typeof designIntentContract.designExecutionHandoff !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff must exist.');
+  } else {
+    if (designIntentContract.designExecutionHandoff.version !== 'ui-handoff-v1') {
+      validationErrors.push('designIntent.designExecutionHandoff.version must equal "ui-handoff-v1".');
     }
-    if (designIntentContract.visualQaPolicy.reportVersion !== 'hybrid-visual-diff-v1') {
-      validationErrors.push('designIntent.visualQaPolicy.reportVersion must equal "hybrid-visual-diff-v1".');
+    if (designIntentContract.designExecutionHandoff.seedMode !== 'structure-first-scaffold') {
+      validationErrors.push('designIntent.designExecutionHandoff.seedMode must equal "structure-first-scaffold".');
     }
-    if (!Array.isArray(designIntentContract.visualQaPolicy.requiredViewports) || designIntentContract.visualQaPolicy.requiredViewports.join('|') !== 'mobile|tablet|desktop') {
-      validationErrors.push('designIntent.visualQaPolicy.requiredViewports must equal ["mobile","tablet","desktop"].');
+    if (designIntentContract.designExecutionHandoff.requiresTaskSpecificRefinement !== true) {
+      validationErrors.push('designIntent.designExecutionHandoff.requiresTaskSpecificRefinement must equal true.');
     }
-
-    const capturePlan = designIntentContract.visualQaPolicy.capturePlan;
-    if (!capturePlan || typeof capturePlan !== 'object') {
-      validationErrors.push('designIntent.visualQaPolicy.capturePlan must exist.');
+    if (!String(designIntentContract.designExecutionHandoff.primaryExperienceGoal || '').trim()) {
+      validationErrors.push('designIntent.designExecutionHandoff.primaryExperienceGoal must be a non-empty string.');
+    }
+    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 (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 (!Array.isArray(componentGraph.nodes) || componentGraph.nodes.length < 2) {
+        validationErrors.push('designIntent.designExecutionHandoff.componentGraph.nodes must list the primary execution nodes.');
       }
-      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']) {
+        if (!String(viewportMutationPlan[viewportKey] || '').trim()) {
+          validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey} 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 (!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.`);
+        }
       }
     }
   }
@@ -817,7 +870,6 @@ export function buildDesignIntentSeedFromSignals({
   primaryDomain,
   features = [],
   initContext,
-  architectureRecommendation = null,
   status = 'seed-needs-design-synthesis',
   supplementalFields = {},
 }) {
@@ -827,7 +879,6 @@ export function buildDesignIntentSeedFromSignals({
     primaryDomain,
     features,
     initContext,
-    architectureRecommendation,
     status,
     supplementalFields,
   });
@@ -843,7 +894,6 @@ export function buildDesignIntentSeedFromSignals({
 export function buildDesignIntentSeed({
   discoveryAnswers,
   initContext,
-  architectureRecommendation,
 }) {
   return buildDesignIntentSeedFromSignals({
     projectName: discoveryAnswers.projectName,
@@ -851,7 +901,6 @@ export function buildDesignIntentSeed({
     primaryDomain: discoveryAnswers.primaryDomain,
     features: discoveryAnswers.features,
     initContext,
-    architectureRecommendation,
     status: 'seed-needs-design-synthesis',
   });
 }