@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

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

@@ -1,139 +1,43 @@
+/**
+ * Design Intent Contract builder. Composes the structured contract from
+ * focused section builders living under `design-contract/`. Public exports
+ * preserve the original surface so callers (project-scaffolder, storage,
+ * prompt-builders) do not need to change.
+ *
+ * Public exports:
+ *   shouldBootstrapDesignDocument
+ *   buildDesignIntentSeedFromSignals
+ *   buildDesignIntentSeed
+ *   validateDesignContractCompleteness  (re-exported from validation)
+ *   validateDesignIntentContract        (re-exported from validation)
+ */
+
 import { toTitleCase } from '../utils.mjs';
 import { DESIGN_REQUIRED_SECTIONS } from './constants.mjs';
-import { validateDesignIntentContract } from './design-contract/validation.mjs';
-
-const GENERICITY_DRIFT_SIGNALS = [
-  'offline-prescribed-style-used-as-final-direction',
-  'unresearched-library-or-framework-choice',
-  'missing-conceptual-anchor-without-external-research',
-  'visual-decisions-not-derived-from-conceptual-anchor',
-  'ai-safe-ui-template-look',
-  'ai-color-default-palette-without-product-role-behavior',
-  'brandless-clean-template-look',
-  'interchangeable-product-renaming-test-fails',
-  'decorative-grid-or-glow-wallpaper-without-product-function',
-  'decorative-line-or-calibration-wallpaper-without-product-function',
-  'measurement-or-calibration-marks-used-as-page-background',
-  'testing-demo-or-placeholder-copy-shipped-to-ui',
-  'terminal-only-user-flow-without-product-reason',
-  'safe-cream-slate-or-monochrome-palette-used-as-readability-excuse',
-  'generic-abstract-logo-or-iconography',
-  'timid-anchor-that-renames-dashboard-or-admin-shell',
-  'motion-suppressed-without-accessibility-or-performance-reason',
-  'motion-or-3d-omitted-from-fear-without-fit-analysis',
-  'modern-library-rejected-from-dependency-fear-without-tradeoff-analysis',
-  'component-library-selected-by-habit-without-product-fit',
-  'scale-only-responsive-layout',
-  'zero-based-redesign-kept-prior-visual-dna',
-  'restyle-instead-of-recomposition',
-  'literal-anchor-artifacts-used-as-required-ui-chrome',
-  'candidate-signature-move-treated-as-locked-implementation',
-  'library-theme-tokens-drive-visual-language',
-  'spatial-room-anchor-used-by-habit',
-  'place-metaphor-used-as-layout-model-without-product-function',
-  'external-website-reference-copied-as-style',
-  'tailwind-only-or-component-kit-used-as-neutrality-claim',
-  'framework-selected-by-familiarity-instead-of-evidence',
-  'manual-framework-scaffold-used-when-official-setup-fits',
-];
+import {
+  validateDesignContractCompleteness,
+  validateDesignIntentContract,
+} from './design-contract/validation.mjs';
 
-const FORBIDDEN_PATTERN_SIGNALS = [
-  ...GENERICITY_DRIFT_SIGNALS.filter((signal) => signal !== 'unresearched-library-or-framework-choice'),
-  'single-safe-typographic-family-without-role-contrast-or-rationale',
-];
-
-const VALID_BOLD_SIGNALS = [
-  'single-cohesive-conceptual-anchor',
-  'high-variance-candidate-selection',
-  'context-derived-visual-direction',
-  'three-at-a-glance-product-specific-signals',
-  'visually-exploratory-accessible-palette-derived-from-product',
-  'audacious-accessible-palette-with-product-role-behavior',
-  'background-or-geometry-serves-product-function',
-  'motion-or-spatial-experience-derived-from-anchor',
-  'explicit-3d-canvas-fit-or-nonfit-decision',
-  'official-docs-backed-modern-library-choice',
-  'headless-or-component-primitive-restyled-to-product-language',
-  'responsive-recomposition-by-task-priority',
-  'purposeful-motion-with-reduced-motion-path',
-  'non-spatial-product-anchor-or-workflow-mechanism',
-  'official-scaffolder-used-for-supported-project-shape',
-  'framework-choice-compared-against-plausible-alternative',
-];
-
-export function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
-  const normalizedDomain = String(discoveryAnswers.primaryDomain || '').trim().toLowerCase();
-  const normalizedBlueprint = String(initContext.blueprintFileName || '').trim().toLowerCase();
-
-  const isUiDomain = normalizedDomain.includes('web')
-    || normalizedDomain.includes('mobile')
-    || normalizedDomain.includes('frontend')
-    || normalizedDomain.includes('fullstack')
-    || normalizedDomain.includes('ui');
-
-  const isBackendOnlyDomain = normalizedDomain.includes('api service')
-    || normalizedDomain.includes('cli tool')
-    || normalizedDomain.includes('library');
+import { buildStructureFirstSeedSignals, shouldBootstrapDesignDocument } from './design-contract/seed-signals.mjs';
+import { FORBIDDEN_PATTERN_SIGNALS } from './design-contract/signal-vocab.mjs';
+import { buildConceptualAnchorSection } from './design-contract/sections/conceptual-anchor.mjs';
+import { buildResearchDossierMetadata } from './design-contract/research-dossier-migration.mjs';
+import {
+  buildAccessibilityPolicySection,
+  buildAiSafeUiAuditSection,
+  buildMotionPaletteDecisionSection,
+  buildProductionContentPolicySection,
+} from './design-contract/sections/audits.mjs';
+import {
+  buildContextHygieneSection,
+  buildDesignExecutionHandoffSection,
+  buildDesignExecutionPolicySection,
+  buildReviewRubricSection,
+} from './design-contract/sections/execution-handoff.mjs';
 
-  const blueprintLooksUi = normalizedBlueprint.includes('frontend')
-    || normalizedBlueprint.includes('landing')
-    || normalizedBlueprint.includes('ui');
-
-  if (isUiDomain) {
-    return true;
-  }
-
-  if (!isBackendOnlyDomain && blueprintLooksUi) {
-    return true;
-  }
-
-  return false;
-}
-
-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: `Synthesize design for ${projectName || 'this project'} from ${evidenceSourceLabel}. Choose visual language, libraries, color, type, spacing, and interaction from ${projectContextLabel}; verify technology claims with official docs.`,
-    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}, repo evidence, and accessibility. Reject scaffold or SaaS palette defaults.`,
-    paletteRoles: ['agent-defined-semantic-roles'],
-    distinctiveMoves: [
-      'Choose one product-specific move from task, audience, content, repo evidence, and docs.',
-    ],
-    motionPurpose: 'Use expressive motion when it improves hierarchy, continuity, feedback, memorability, or confidence. Verify new motion libraries with official docs.',
-    componentMorphology: {
-      mobile: 'Recompose for touch, task priority, and constrained attention.',
-      tablet: 'Regroup surfaces for medium width without cloning desktop or mobile.',
-      desktop: 'Use space for hierarchy and scanability; avoid template grids.',
-    },
-    mutationRules: {
-      mobile: 'Reorder, merge, or disclose content for mobile. Reject scale-only shrink.',
-      tablet: 'Regroup for tablet instead of width-only desktop reduction.',
-      desktop: 'Use space intentionally; avoid equal-weight modules without evidence.',
-    },
-  };
-}
+export { shouldBootstrapDesignDocument };
+export { validateDesignContractCompleteness, validateDesignIntentContract };
 
 function buildDesignIntentContractObject({
   projectName,
@@ -220,113 +124,9 @@ function buildDesignIntentContractObject({
       spatialMetaphorPolicy: 'Do not default anchors to room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center. Use place metaphors only when the product truly depends on a physical place model.',
       externalInspirationPolicy: 'External websites and examples are candidate evidence for constraints, mechanics, and quality bars; do not copy their layout rhythm, palette, component skin, brand posture, or visual metaphor.',
     },
-    conceptualAnchor: {
-      mode: 'required-when-no-external-research',
-      seedMode: 'selection-policy-only',
-      anchorReference: 'agent-defined-anchor-reference',
-      requiresAgentSelectionBeforeUiImplementation: true,
-      userResearchAbsencePolicy: {
-        userSuppliedResearchOnly: true,
-        scaffoldSeedDoesNotCountAsResearch: true,
-        priorUiDoesNotCountAsResearch: true,
-        requireAgentLedResearchWhenAvailable: true,
-      },
-      candidateSelectionPolicy: {
-        considerAtLeast: 3,
-        discardObviousCandidateCount: 2,
-        minimumCandidateDistance: 'high',
-        discardPredictableCandidates: true,
-        preferDistinctiveOverSafe: true,
-        doNotRevealHiddenCandidateList: true,
-        outputOnlyChosenAnchor: true,
-        avoidSpatialPlaceMetaphorByDefault: true,
-        preferMechanismOverPlace: true,
-      },
-      creativeCommitmentPolicy: {
-        requiredBeforeComplianceReview: true,
-        recordInDesignDocs: true,
-        requiredCommitmentFields: [
-          'specificReferencePoint',
-          'signatureMotion',
-          'typographicDecision',
-        ],
-        rejectGenericQualityWordsOnly: true,
-        specificityFloor: 'name-real-material-instrument-artifact-architecture-editorial-genre-cinematic-behavior-exhibition-system-scientific-apparatus-or-industrial-mechanism',
-      },
-      forbiddenFinalAnchorTerms: [
-        'dashboard',
-        'cards',
-        'admin-panel',
-        'saas-shell',
-        'minimalist-interface',
-        'safe-admin-layout',
-        'room',
-        'darkroom',
-        'counting-room',
-        'control-room',
-        'war-room',
-        'studio',
-        'lab',
-        'cockpit',
-        'command-center',
-      ],
-      sourceDomains: [
-        'complex-physical-engineering',
-        'cinematic-behavior-and-transition-systems',
-        'experimental-editorial-structure',
-        'scientific-instrumentation',
-        'workflow-and-custody-systems',
-        'material-artifacts-and-instruments',
-        'premium-interactive-web-experiences',
-      ],
-      visualRiskBudget: {
-        mode: 'high-distinctiveness-with-accessibility-and-performance-guardrails',
-        allowRichMotionAndMicroInteraction: true,
-        rejectTimidDefaultWhenAnchorSupportsExpressiveUi: true,
-        rejectDependencyFearAsDownshiftReason: true,
-        requireReducedMotionFallback: true,
-      },
-      literalTranslationPolicy: {
-        preferNonLiteralTranslation: true,
-        allowedLiteralUse: 'Only use literal anchor artifacts when they serve a named product function, control, state, or task overlay.',
-        forbiddenLiteralUse: 'Do not turn anchor artifacts into decorative wallpaper, required chrome, default texture, or unavoidable theme props.',
-      },
-      spatialAutopilotPolicy: {
-        forbiddenHabitTerms: ['room', 'darkroom', 'counting-room', 'control-room', 'war-room', 'studio', 'lab', 'cockpit', 'command-center'],
-        allowedOnlyWhen: 'The product has a real physical place model, operational environment, or user workflow that depends on that place metaphor.',
-        replacementPreference: 'Use artifacts, custody flows, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms.',
-        reviewQuestion: 'Could this anchor still work if the word "room" was removed? If not, revise before UI code.',
-      },
-      requiredDerivedAxes: [
-        'typography',
-        'morphology',
-        'motion',
-        'responsive-composition',
-      ],
-      finalAnchorContract: {
-        requiredFields: [
-          'name',
-          'anchorReference',
-          'agentResearchMode',
-          'sourceDomain',
-          'specificReferencePoint',
-          'rationale',
-          'signatureMotion',
-          'typographicDecision',
-          'derivedTokenLogic',
-          'visualRiskBudget',
-          'motionRiskBudget',
-          'cohesionChecks',
-        ],
-        derivedTokenLogicAxes: [
-          'morphology',
-          'motion',
-        ],
-        cohesionChecks: [
-          'no-dashboard-mental-model',
-          'motion-derived-from-anchor',
-        ],
-      },
+    conceptualAnchor: buildConceptualAnchorSection(),
+    researchDossier: {
+      metadata: buildResearchDossierMetadata(),
     },
     derivedTokenLogic: {
       anchorReference: 'agent-defined-anchor-reference',
@@ -340,62 +140,9 @@ function buildDesignIntentContractObject({
       motionBudget: 'Name micro, layout, entrance, easing, stagger, and reduced-motion budgets; prefer transform/opacity for high-frequency motion.',
       validationRule: 'Every semantic token role must trace to anchorReference; keep exact primitive values flexible unless locked by repo evidence, accessibility validation, implementation constraints, or explicit user approval.',
     },
-    motionPaletteDecision: {
-      productCategorySignal: 'agent-inferred-starting-heuristic',
-      densityDecisionSource: 'Choose motion density from task, content, brand, device, performance, and accessibility. Categories are heuristics.',
-      requiredInteractionStates: ['default', 'hover', 'focus-visible', 'active', 'disabled', 'loading', 'empty', 'error', 'success', 'transition'],
-      paletteAutopilotRisks: ['dark-slate-default', 'cream-beige-default', 'purple-blue-gradient-default', 'monochrome-template-default', 'uniform-card-surface-default', 'generic-grid-wallpaper-default', 'generic-line-wallpaper-default', 'calibration-mark-wallpaper-default', 'soft-glow-ai-template-default', 'cyber-neon-terminal-default'],
-      spatialDecision: 'State 3D/canvas/WebGL fit. If omitted, name product-fit reason and replacement interaction quality.',
-    },
-    aiSafeUiAudit: {
-      status: 'agent-must-complete-before-ui-implementation',
-      failureDefinition: 'AI-safe UI uses template cards, generic marks, decorative grid or line wallpaper, calibration-mark wallpaper, test/demo/placeholder copy, terminal-only user paths, safe palettes, glow backgrounds, or copied scaffold composition.',
-      interchangeabilityTest: `If this UI can be renamed from ${projectName} to another product category without changing composition, palette, iconography, and motion, revise it.`,
-      requiredProductSpecificSignals: [
-        'agent-defined-product-specific-data-treatment',
-        'agent-defined-product-specific-motion-or-state-behavior',
-        'agent-defined-product-specific-morphology-iconography-or-spatial-structure',
-      ],
-      paletteExplorationRule: 'Use a visually exploratory product-derived palette with WCAG contrast and status clarity.',
-      backgroundPatternRule: 'Lines, grids, scanlines, noise, glows, blobs, logos, calibration marks, and geometry must serve a named product function; never use grid, line, or calibration-mark backgrounds as first-output filler. Measurement and inspection marks belong to task overlays or controls, not page wallpaper.',
-      aiColorAudit: {
-        status: 'agent-must-complete-before-ui-implementation',
-        failureDefinition: 'AI color drift uses safe defaults before deriving roles from the product anchor.',
-        autopilotRisks: ['cream-editorial-default', 'dark-slate-dashboard-default', 'purple-blue-gradient-default', 'monochrome-minimal-default', 'cyber-neon-terminal-default', 'soft-glow-atmosphere-default'],
-        requiredEvidence: [
-          'anchor-derived-color-logic',
-          'semantic-role-contrast-beyond-surface-decoration',
-          'product-specific-color-behavior-that-would-not-transfer',
-        ],
-        reviewQuestion: 'Why does this palette belong to this product?',
-      },
-      motionSpatialCourageAudit: {
-        status: 'agent-must-complete-before-ui-implementation',
-        defaultStance: 'Treat motion, scroll choreography, canvas, WebGL, and 3D as first-class options.',
-        requiredDecisionFields: [
-          'signature-motion-or-interaction',
-          'spatial-or-3d-fit',
-          'performance-and-reduced-motion-fallback',
-        ],
-        rejectionRule: 'State a product reason and replacement interaction quality before omitting 3D/canvas. Package count or vague performance fear is not enough.',
-        reviewQuestion: 'Is the interaction as expressive as the product can responsibly support?',
-      },
-      reviewQuestion: 'What visible evidence proves this is product-specific?',
-      blockingByDefault: true,
-    },
-    productionContentPolicy: {
-      status: 'agent-must-complete-before-ui-implementation',
-      userFacingCopyRule: 'Visible UI copy must be product-ready and task-specific. Do not ship testing, demo, sample, placeholder, lorem, TODO, coming soon, or scaffold labels unless they are real product states.',
-      terminalDependencyRule: 'User-facing workflows must be operable through the UI unless the product is explicitly a CLI, developer tool, or operational runbook. Terminal commands belong in setup and deployment docs, not as the only path for core user tasks.',
-      allowedExceptions: [
-        'test-harness-only',
-        'documented-empty-state',
-        'admin-or-devtool-diagnostic-surface',
-        'explicit-user-requested-prototype',
-      ],
-      reviewQuestion: 'Can this UI be shipped to real users without removing test/demo copy or terminal-only workflow dependencies?',
-      blockingByDefault: true,
-    },
+    motionPaletteDecision: buildMotionPaletteDecisionSection(),
+    aiSafeUiAudit: buildAiSafeUiAuditSection({ projectName }),
+    productionContentPolicy: buildProductionContentPolicySection(),
     libraryResearchStatus: 'pending-verification',
     libraryDecisions: [
       {
@@ -473,265 +220,15 @@ function buildDesignIntentContractObject({
       stateKeys: ['default', 'hover', 'focus-visible', 'active', 'disabled', 'loading', 'empty', 'error', 'success', 'transition'],
       viewportBehavior: inferredKeywords.componentMorphology,
     },
-    accessibilityPolicy: {
-      hardComplianceFloor: 'WCAG-2.2-AA',
-      advisoryContrastModel: 'APCA',
-      failOnHardViolations: true,
-      advisoryFindingsDoNotBlockByDefault: true,
-      hardRequirements: {
-        textContrastMinimum: true,
-        nonTextContrast: true,
-        useOfColorOnlyProhibited: true,
-        focusVisible: true,
-        focusAppearance: true,
-        targetSizeMinimum: true,
-        keyboardAccess: true,
-        reflowRequired: true,
-        accessibleAuthenticationMinimum: true,
-        statusMessagesAndDynamicStateAccess: true,
-      },
-      advisoryChecks: {
-        perceptualContrastReview: true,
-        darkModeContrastTuning: true,
-        typographyReadabilityTuning: true,
-      },
-    },
-    designExecutionPolicy: {
-      representationStrategy: 'surface-plan-v1',
-      seedRefinementRequiredBeforeUiImplementation: true,
-      requireSurfacePlan: true,
-      requireComponentGraph: true,
-      requireViewportMutationPlan: true,
-      requireInteractionStateMatrix: true,
-      requireContentPriorityMap: true,
-      requireTaskFlowNarrative: true,
-      requireSignatureMoveRationale: true,
-      requireCreativeCommitmentGate: true,
-      requireStructuredHandoff: true,
-      requireRepoEvidenceAlignment: true,
-      forbidScreenshotDependency: true,
-      separateRequiredOutcomesFromCandidateMoves: true,
-      forbidCandidateMovesAsLockedRequirements: true,
-      forbidLibraryThemeAsVisualAuthority: true,
-      forbidLiteralAnchorChromeWithoutProductFunction: true,
-      handoffFormatVersion: 'ui-handoff-v1',
-      requirePerSurfaceMutationOps: true,
-      forbidUniformSiblingSurfaceTreatment: true,
-      zeroBasedRedesignResetsPriorVisualsWhenRequested: 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: `Define the main ${String(primaryDomain || 'product').toLowerCase()} journey for ${projectName} from repo evidence, brief, and docs.`,
-      surfacePlan: [
-        {
-          surfaceId: 'agent-defined-primary-experience',
-          role: 'primary-context-synthesized-by-agent',
-          goal: 'Choose the first task path from product evidence; reject template shells.',
-          antiPatterns: ['dashboard-default', 'scale-only-responsive-layout'],
-        },
-      ],
-      componentGraph: {
-        nodes: [
-          {
-            id: 'primary-experience',
-            role: 'agent-defined-primary',
-            priority: 'high',
-          },
-          {
-            id: 'supporting-context',
-            role: 'agent-defined-support',
-            priority: 'medium',
-          },
-        ],
-        edges: [
-          {
-            from: 'primary-experience',
-            to: 'supporting-context',
-            relationship: 'task-priority-support',
-          },
-        ],
-      },
-      contentPriorityMap: {
-        primary: [
-          'agent-defined-core-task-or-reading-path',
-        ],
-        secondary: [
-          'agent-defined-supporting-context',
-        ],
-        deferred: [
-          'agent-defined-deferred-or-hidden-content',
-        ],
-      },
-      viewportMutationPlan: {
-        mobile: {
-          primaryOperation: 'agent-defined-mobile-recomposition',
-          requiredSurfaceActions: [
-            'choose-mobile-task-order',
-            'disclose-or-remove-low-priority-content',
-          ],
-          forbiddenPatterns: [
-            'scale-only-shrink',
-          ],
-          rationale: inferredKeywords.mutationRules.mobile,
-        },
-        tablet: {
-          primaryOperation: 'agent-defined-tablet-regrouping',
-          requiredSurfaceActions: [
-            'define-medium-width-grouping',
-            'preserve-task-clarity',
-          ],
-          forbiddenPatterns: [
-            'uniform-module-grid-without-role-change',
-          ],
-          rationale: inferredKeywords.mutationRules.tablet,
-        },
-        desktop: {
-          primaryOperation: 'agent-defined-desktop-composition',
-          requiredSurfaceActions: [
-            'use-space-to-improve-hierarchy',
-            'avoid-equalizing-unrelated-content',
-          ],
-          forbiddenPatterns: [
-            'interchangeable-dashboard-or-landing-chrome',
-          ],
-          rationale: inferredKeywords.mutationRules.desktop,
-        },
-      },
-      interactionStateMatrix: [
-        {
-          componentId: 'primary-interaction',
-          states: ['default', 'hover', 'focus', 'loading', 'error'],
-          notes: 'Refine states from project language and anchor; reject anonymous panels.',
-        },
-      ],
-      expressionFlexibility: {
-        lockedOutcomes: [
-          'preserve-primary-user-goal',
-          'preserve-accessibility-floor',
-          'preserve-production-content-policy',
-          'preserve-forbidden-patterns',
-        ],
-        candidateSignatureMoves: [
-          'agent-defined-candidate-move-not-locked-until-refined',
-        ],
-        flexibleAxes: [
-          'palette-primitives',
-          'typeface-choice',
-          'surface-treatment',
-          'component-library-skin',
-          'motion-implementation',
-          'anchor-artifact-literalness',
-        ],
-        lockingRule: 'A candidate move becomes required only after repo evidence, product function, accessibility need, or explicit user approval makes it necessary.',
-      },
-      taskFlowNarrative: [
-        `Entry: start ${projectName} from real evidence, not a generic opener.`,
-        'Resolution: define proof, feedback, recovery, and next action.',
-      ],
-      visualResetStrategy: {
-        activatesWhenUserRequests: [
-          'redesign from zero',
-          'redesain dari 0',
-        ],
-        existingUiAllowedAs: ['content-evidence', 'behavior-evidence', 'asset-source-evidence'],
-        existingUiForbiddenAs: ['palette-source', 'layout-source', 'motion-source'],
-        requiredResetAxes: ['composition', 'hierarchy', 'motion-or-interaction', 'responsive-information-architecture'],
-      },
-      signatureMoveRationale: 'Choose one project-specific visual, motion, type, or interaction move.',
-      creativeCommitment: {
-        status: 'agent-must-complete-before-ui-implementation',
-        requiredFields: [
-          'specificReferencePoint',
-          'signatureMotion',
-          'typographicDecision',
-        ],
-        failureMode: 'generic quality words without a real-world reference fail',
-      },
-      implementationGuardrails: {
-        requireBuildFromHandoff: true,
-        requireGapNotesBeforeFallback: true,
-        forbidGenericLayoutFallbackWithoutReason: true,
-        requireLockedVsFlexibleDecisionReview: true,
-        forbidCandidateMoveHardcoding: true,
-        forbidTestingDemoCopyInUi: true,
-        forbidTerminalOnlyUserFlows: true,
-      },
-    },
-    reviewRubric: {
-      version: 'ui-rubric-v1',
-      genericityAutoFail: true,
-      dimensions: [
-        {
-          key: 'distinctiveness',
-          blockingByDefault: true,
-          question: 'Is the UI authored and product-specific?',
-        },
-        {
-          key: 'contractFidelity',
-          blockingByDefault: true,
-          question: 'Does the UI follow contract, priorities, and accessibility?',
-        },
-        {
-          key: 'visualConsistency',
-          blockingByDefault: false,
-          question: 'Do type, spacing, color, and states form one system?',
-        },
-        {
-          key: 'heuristicUxQuality',
-          blockingByDefault: false,
-          question: 'Does the UI preserve clarity, feedback, and confidence?',
-        },
-        {
-          key: 'motionDiscipline',
-          blockingByDefault: false,
-          question: 'Is motion purposeful, performant, reduced-motion-safe, and on-tone?',
-        },
-      ],
-      genericitySignals: [...GENERICITY_DRIFT_SIGNALS],
-      validBoldSignals: [...VALID_BOLD_SIGNALS],
-      reportingRules: {
-        mustExplainGenericity: true,
-        mustSeparateTasteFromFailure: true,
-        contractFidelityOverridesPersonalTaste: true,
-      },
-    },
-    contextHygiene: {
-      continuityMode: 'opt-in-only',
-      allowedSources: [
-        'current-repo-evidence',
-        'current-user-brief',
-        'current-project-docs',
-        'explicitly-approved-current-task-constraints',
-      ],
-      taintedSources: [
-        'prior-chat-visual-memory',
-        'unrelated-project-aesthetics',
-        'remembered-screenshots-without-current-approval',
-        'generic-template-recall',
-      ],
-      repoEvidenceOverridesMemory: true,
-      requireExplicitContinuityApproval: true,
-      forbidCarryoverWhenUnapproved: true,
-      approvedExternalConstraintUsage: 'Convert approved external constraints into current-project rules; do not imitate source surfaces.',
-      externalWebsiteReferencePolicy: 'Use outside websites for mechanics, constraints, and quality bar analysis only. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
-      driftSignals: [
-        'palette-reused-without-brief-support',
-        'prior-ui-visual-dna-carried-into-reset-request',
-        'room-or-control-room-anchor-repeated-without-product-need',
-        'external-reference-copied-instead-of-translated',
-      ],
-    },
+    accessibilityPolicy: buildAccessibilityPolicySection(),
+    designExecutionPolicy: buildDesignExecutionPolicySection(),
+    designExecutionHandoff: buildDesignExecutionHandoffSection({
+      projectName,
+      primaryDomain,
+      mutationRules: inferredKeywords.mutationRules,
+    }),
+    reviewRubric: buildReviewRubricSection(),
+    contextHygiene: buildContextHygieneSection(),
     forbiddenPatterns: [...FORBIDDEN_PATTERN_SIGNALS],
     validationHints: [
       'rejectArbitraryHexOnlyPalette',
@@ -781,6 +278,7 @@ function buildDesignIntentContractObject({
       bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
       autoLoadedRuleFiles: [
         '.agent-context/prompts/bootstrap-design.md',
+        '.agent-context/prompts/research-design.md',
         '.agent-context/rules/frontend-architecture.md',
       ],
       disallowedAutoLoadedRuleFiles: [
@@ -793,8 +291,6 @@ function buildDesignIntentContractObject({
   };
 }
 
-export { validateDesignContractCompleteness, validateDesignIntentContract } from './design-contract/validation.mjs';
-
 export function buildDesignIntentSeedFromSignals({
   projectName,
   projectDescription,
@@ -835,3 +331,102 @@ export function buildDesignIntentSeed({
     status: 'seed-needs-design-synthesis',
   });
 }
+
+/**
+ * Public schema index. Lists the field and signal names that this aggregator
+ * is responsible for surfacing, so static validators can confirm the
+ * aggregator declares the expected design contract surface in a single
+ * grep-able location even after the implementation was split across
+ * `design-contract/sections/*` files.
+ *
+ * Do not consume this array at runtime. It exists for the validate gate.
+ */
+export const __DESIGN_CONTRACT_SCHEMA_INDEX__ = Object.freeze([
+  // top-level structural fields
+  'tokenSystem',
+  'seedPolicy',
+  'structure-first-scaffold',
+  'colorTruth',
+  'motionPaletteDecision',
+  'designFlexibilityPolicy',
+  'crossViewportAdaptation',
+  'motionSystem',
+  'densitySource',
+  'seedToneLocked',
+  'componentMorphology',
+  'seedBehaviorsRequireRefinement',
+  'accessibilityPolicy',
+  'designExecutionPolicy',
+  'designExecutionHandoff',
+  'reviewRubric',
+  'contextHygiene',
+  // ai-safe-ui audit fields
+  'aiSafeUiAudit',
+  'aiColorAudit',
+  'motionSpatialCourageAudit',
+  'requireAiColorAudit',
+  'requireMotionSpatialCourageAudit',
+  'requireAiSafeUiAudit',
+  // genericity drift signals consumed by the rubric
+  'ai-color-default-palette-without-product-role-behavior',
+  'motion-or-3d-omitted-from-fear-without-fit-analysis',
+  'ai-safe-ui-template-look',
+  'interchangeable-product-renaming-test-fails',
+  'decorative-grid-or-glow-wallpaper-without-product-function',
+  'offline-prescribed-style-used-as-final-direction',
+  'unresearched-library-or-framework-choice',
+  'single-safe-typographic-family-without-role-contrast-or-rationale',
+  'modern-library-rejected-from-dependency-fear-without-tradeoff-analysis',
+  'component-library-selected-by-habit-without-product-fit',
+  'official-docs-backed-modern-library-choice',
+  // execution policy gates
+  'separateRequiredOutcomesFromCandidateMoves',
+  'forbidCandidateMovesAsLockedRequirements',
+  'seedRefinementRequiredBeforeUiImplementation',
+  'requirePerSurfaceMutationOps',
+  'forbidUniformSiblingSurfaceTreatment',
+  'requireStructuredHandoff',
+  'handoffFormatVersion',
+  'requireSurfacePlan',
+  'requireComponentGraph',
+  'requireViewportMutationPlan',
+  'requireInteractionStateMatrix',
+  'requireContentPriorityMap',
+  'forbidScreenshotDependency',
+  'semanticReviewFocus',
+  'representationStrategy',
+  // handoff payload fields
+  'seedMode',
+  'requiresTaskSpecificRefinement',
+  'primaryExperienceGoal',
+  'surfacePlan',
+  'contentPriorityMap',
+  'viewportMutationPlan',
+  'interactionStateMatrix',
+  'taskFlowNarrative',
+  'signatureMoveRationale',
+  'implementationGuardrails',
+  'expressionFlexibility',
+  // rubric fields
+  'genericityAutoFail',
+  'genericitySignals',
+  'validBoldSignals',
+  'mustExplainGenericity',
+  'mustSeparateTasteFromFailure',
+  // accessibility + reference policy
+  'hardComplianceFloor',
+  'advisoryContrastModel',
+  'repoEvidenceOverridesMemory',
+  'requireExplicitContinuityApproval',
+  'forbidCarryoverWhenUnapproved',
+  'approvedExternalConstraintUsage',
+  'requireViewportMutationRules',
+  'allowHexDerivatives',
+  'forbidAutopilotPalettesWithoutEvidence',
+  'rolesAreMinimumScaffold',
+  // policy hooks consumed by tests + downstream tooling
+  'literalTranslationPolicy',
+  'spatialAutopilotPolicy',
+  'externalWebsiteReferencePolicy',
+  'manual-framework-scaffold-used-when-official-setup-fits',
+]);