@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

package/lib/cli/project-scaffolder/design-contract/validation/anchor-validators.mjs

@@ -0,0 +1,456 @@
+/**
+ * Conceptual anchor and math systems validators: enforces the anti-generic
+ * anchor selection contract, source domains, visual risk budget, literal
+ * translation policy, derived axes, final anchor contract, and the math
+ * systems block.
+ */
+
+import { hasNonEmptyString } from './helpers.mjs';
+
+const SEED_STATUSES = new Set([
+  'seed-needs-design-synthesis',
+  'seed-generated-during-init',
+  'seed-generated-during-upgrade',
+]);
+
+function validateUserResearchAbsencePolicy(conceptualAnchor, validationErrors) {
+  const userResearchAbsencePolicy = conceptualAnchor.userResearchAbsencePolicy;
+  if (!userResearchAbsencePolicy || typeof userResearchAbsencePolicy !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.userResearchAbsencePolicy must exist.');
+    return;
+  }
+  if (userResearchAbsencePolicy.userSuppliedResearchOnly !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.userResearchAbsencePolicy.userSuppliedResearchOnly must equal true.');
+  }
+  if (userResearchAbsencePolicy.scaffoldSeedDoesNotCountAsResearch !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.userResearchAbsencePolicy.scaffoldSeedDoesNotCountAsResearch must equal true.');
+  }
+  if (userResearchAbsencePolicy.priorUiDoesNotCountAsResearch !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.userResearchAbsencePolicy.priorUiDoesNotCountAsResearch must equal true.');
+  }
+  if (userResearchAbsencePolicy.requireAgentLedResearchWhenAvailable !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.userResearchAbsencePolicy.requireAgentLedResearchWhenAvailable must equal true.');
+  }
+}
+
+function validateCandidateSelectionPolicy(conceptualAnchor, validationErrors) {
+  const candidateSelectionPolicy = conceptualAnchor.candidateSelectionPolicy;
+  if (!candidateSelectionPolicy || typeof candidateSelectionPolicy !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy must exist.');
+    return;
+  }
+  if (candidateSelectionPolicy.considerAtLeast < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.considerAtLeast must be at least 3.');
+  }
+  if (candidateSelectionPolicy.discardObviousCandidateCount < 2) {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.discardObviousCandidateCount must be at least 2.');
+  }
+  if (candidateSelectionPolicy.minimumCandidateDistance !== 'high') {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.minimumCandidateDistance must equal "high".');
+  }
+  if (candidateSelectionPolicy.discardPredictableCandidates !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.discardPredictableCandidates must equal true.');
+  }
+  if (candidateSelectionPolicy.preferDistinctiveOverSafe !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.preferDistinctiveOverSafe must equal true.');
+  }
+  if (candidateSelectionPolicy.doNotRevealHiddenCandidateList !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.doNotRevealHiddenCandidateList must equal true.');
+  }
+  if (candidateSelectionPolicy.outputOnlyChosenAnchor !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.candidateSelectionPolicy.outputOnlyChosenAnchor must equal true.');
+  }
+}
+
+function validateCreativeCommitmentPolicy(conceptualAnchor, validationErrors) {
+  const creativeCommitmentPolicy = conceptualAnchor.creativeCommitmentPolicy;
+  if (!creativeCommitmentPolicy || typeof creativeCommitmentPolicy !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.creativeCommitmentPolicy must exist.');
+    return;
+  }
+  if (creativeCommitmentPolicy.requiredBeforeComplianceReview !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.creativeCommitmentPolicy.requiredBeforeComplianceReview must equal true.');
+  }
+  if (creativeCommitmentPolicy.recordInDesignDocs !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.creativeCommitmentPolicy.recordInDesignDocs must equal true.');
+  }
+  if (
+    !Array.isArray(creativeCommitmentPolicy.requiredCommitmentFields)
+    || !creativeCommitmentPolicy.requiredCommitmentFields.includes('specificReferencePoint')
+    || !creativeCommitmentPolicy.requiredCommitmentFields.includes('signatureMotion')
+    || !creativeCommitmentPolicy.requiredCommitmentFields.includes('typographicDecision')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.creativeCommitmentPolicy.requiredCommitmentFields must include specificReferencePoint, signatureMotion, and typographicDecision.');
+  }
+  if (creativeCommitmentPolicy.rejectGenericQualityWordsOnly !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.creativeCommitmentPolicy.rejectGenericQualityWordsOnly must equal true.');
+  }
+}
+
+function validateVisualRiskBudgetAndLiteralPolicy(conceptualAnchor, validationErrors) {
+  const visualRiskBudget = conceptualAnchor.visualRiskBudget;
+  if (!visualRiskBudget || typeof visualRiskBudget !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.visualRiskBudget must exist.');
+  } else {
+    if (visualRiskBudget.mode !== 'high-distinctiveness-with-accessibility-and-performance-guardrails') {
+      validationErrors.push('designIntent.conceptualAnchor.visualRiskBudget.mode must preserve high-distinctiveness guardrails.');
+    }
+    if (visualRiskBudget.allowRichMotionAndMicroInteraction !== true) {
+      validationErrors.push('designIntent.conceptualAnchor.visualRiskBudget.allowRichMotionAndMicroInteraction must equal true.');
+    }
+    if (visualRiskBudget.rejectTimidDefaultWhenAnchorSupportsExpressiveUi !== true) {
+      validationErrors.push('designIntent.conceptualAnchor.visualRiskBudget.rejectTimidDefaultWhenAnchorSupportsExpressiveUi must equal true.');
+    }
+    if (visualRiskBudget.requireReducedMotionFallback !== true) {
+      validationErrors.push('designIntent.conceptualAnchor.visualRiskBudget.requireReducedMotionFallback must equal true.');
+    }
+  }
+
+  const literalTranslationPolicy = conceptualAnchor.literalTranslationPolicy;
+  if (!literalTranslationPolicy || typeof literalTranslationPolicy !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy must exist.');
+    return;
+  }
+  if (literalTranslationPolicy.preferNonLiteralTranslation !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy.preferNonLiteralTranslation must equal true.');
+  }
+  if (!hasNonEmptyString(literalTranslationPolicy.allowedLiteralUse)) {
+    validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy.allowedLiteralUse must be a non-empty string.');
+  }
+  if (!String(literalTranslationPolicy.forbiddenLiteralUse || '').includes('decorative wallpaper')) {
+    validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy.forbiddenLiteralUse must reject decorative wallpaper.');
+  }
+}
+
+function validateFinalAnchorContract(conceptualAnchor, validationErrors) {
+  if (
+    !Array.isArray(conceptualAnchor.requiredDerivedAxes)
+    || !conceptualAnchor.requiredDerivedAxes.includes('typography')
+    || !conceptualAnchor.requiredDerivedAxes.includes('responsive-composition')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.requiredDerivedAxes must include typography and responsive-composition.');
+  }
+  const finalAnchorContract = conceptualAnchor.finalAnchorContract;
+  if (!finalAnchorContract || typeof finalAnchorContract !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.finalAnchorContract must exist.');
+    return;
+  }
+  if (
+    !Array.isArray(finalAnchorContract.requiredFields)
+    || !finalAnchorContract.requiredFields.includes('anchorReference')
+    || !finalAnchorContract.requiredFields.includes('agentResearchMode')
+    || !finalAnchorContract.requiredFields.includes('specificReferencePoint')
+    || !finalAnchorContract.requiredFields.includes('signatureMotion')
+    || !finalAnchorContract.requiredFields.includes('typographicDecision')
+    || !finalAnchorContract.requiredFields.includes('derivedTokenLogic')
+    || !finalAnchorContract.requiredFields.includes('visualRiskBudget')
+    || !finalAnchorContract.requiredFields.includes('motionRiskBudget')
+    || !finalAnchorContract.requiredFields.includes('cohesionChecks')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.finalAnchorContract.requiredFields must require anchorReference, agentResearchMode, specificReferencePoint, signatureMotion, typographicDecision, derivedTokenLogic, visualRiskBudget, motionRiskBudget, and cohesionChecks.');
+  }
+  if (
+    !Array.isArray(finalAnchorContract.derivedTokenLogicAxes)
+    || !finalAnchorContract.derivedTokenLogicAxes.includes('motion')
+    || !finalAnchorContract.derivedTokenLogicAxes.includes('morphology')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.finalAnchorContract.derivedTokenLogicAxes must include motion and morphology.');
+  }
+  if (
+    !Array.isArray(finalAnchorContract.cohesionChecks)
+    || !finalAnchorContract.cohesionChecks.includes('no-dashboard-mental-model')
+    || !finalAnchorContract.cohesionChecks.includes('motion-derived-from-anchor')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.finalAnchorContract.cohesionChecks must reject dashboard mental models and require motion derivation.');
+  }
+}
+
+export function validateConceptualAnchor(designIntentContract, validationErrors) {
+  if (!designIntentContract.conceptualAnchor || typeof designIntentContract.conceptualAnchor !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor must exist.');
+    return validationErrors;
+  }
+
+  const conceptualAnchor = designIntentContract.conceptualAnchor;
+  const isSeedStatus = SEED_STATUSES.has(designIntentContract.status);
+
+  if (conceptualAnchor.mode !== 'required-when-no-external-research') {
+    validationErrors.push('designIntent.conceptualAnchor.mode must equal "required-when-no-external-research".');
+  }
+  if (conceptualAnchor.seedMode !== 'selection-policy-only') {
+    validationErrors.push('designIntent.conceptualAnchor.seedMode must equal "selection-policy-only".');
+  }
+  if (conceptualAnchor.requiresAgentSelectionBeforeUiImplementation !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.requiresAgentSelectionBeforeUiImplementation must equal true.');
+  }
+  if (!hasNonEmptyString(conceptualAnchor.anchorReference)) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorReference must be a stable non-empty ID.');
+  }
+
+  validateUserResearchAbsencePolicy(conceptualAnchor, validationErrors);
+  validateCandidateSelectionPolicy(conceptualAnchor, validationErrors);
+  validateCreativeCommitmentPolicy(conceptualAnchor, validationErrors);
+
+  if (
+    !Array.isArray(conceptualAnchor.forbiddenFinalAnchorTerms)
+    || !conceptualAnchor.forbiddenFinalAnchorTerms.includes('dashboard')
+    || !conceptualAnchor.forbiddenFinalAnchorTerms.includes('cards')
+    || !conceptualAnchor.forbiddenFinalAnchorTerms.includes('safe-admin-layout')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.forbiddenFinalAnchorTerms must reject basic UI labels.');
+  }
+  if (
+    !Array.isArray(conceptualAnchor.sourceDomains)
+    || conceptualAnchor.sourceDomains.length < 4
+    || !conceptualAnchor.sourceDomains.includes('complex-physical-engineering')
+    || !conceptualAnchor.sourceDomains.includes('cinematic-behavior-and-transition-systems')
+    || !conceptualAnchor.sourceDomains.includes('workflow-and-custody-systems')
+    || !conceptualAnchor.sourceDomains.includes('premium-interactive-web-experiences')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.sourceDomains must list broad non-template anchor domains.');
+  }
+
+  validateVisualRiskBudgetAndLiteralPolicy(conceptualAnchor, validationErrors);
+  validateFinalAnchorContract(conceptualAnchor, validationErrors);
+  validateCategoryCodes(conceptualAnchor, validationErrors, { isSeedStatus });
+  validateMorphologicalExploration(conceptualAnchor, validationErrors, { isSeedStatus });
+  validateAnchorCandidates(conceptualAnchor, validationErrors, { isSeedStatus });
+  return validationErrors;
+}
+
+export function validateMathSystems(designIntentContract, validationErrors) {
+  if (!designIntentContract.mathSystems || typeof designIntentContract.mathSystems !== 'object') {
+    validationErrors.push('designIntent.mathSystems must exist.');
+    return validationErrors;
+  }
+  if (!String(designIntentContract.mathSystems.typographyScaleRatio || '').trim()) {
+    validationErrors.push('designIntent.mathSystems.typographyScaleRatio must describe the chosen or pending type scale decision.');
+  }
+  if (!String(designIntentContract.mathSystems.baseGridUnit || '').trim()) {
+    validationErrors.push('designIntent.mathSystems.baseGridUnit must describe the chosen or pending spacing grid decision.');
+  }
+  return validationErrors;
+}
+
+function validateCategoryCodes(conceptualAnchor, validationErrors, options = {}) {
+  const { isSeedStatus = false } = options;
+  const categoryCodes = conceptualAnchor.categoryCodes;
+  if (!categoryCodes || typeof categoryCodes !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes must exist (Section 3 of research-design.md).');
+    return;
+  }
+  if (categoryCodes.mode !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.mode must equal "agent-must-complete-before-ui-implementation".');
+  }
+  if (categoryCodes.blockingByDefault !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.blockingByDefault must equal true.');
+  }
+  if (categoryCodes.researchBriefSection !== 'Section 3') {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.researchBriefSection must equal "Section 3".');
+  }
+  if (!hasNonEmptyString(categoryCodes.researchBriefPath) || !categoryCodes.researchBriefPath.includes('research-design.md')) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.researchBriefPath must point to the research-design.md brief.');
+  }
+  if (!Number.isInteger(categoryCodes.minimumEntries) || categoryCodes.minimumEntries < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.minimumEntries must be an integer >= 3.');
+  }
+  if (!hasNonEmptyString(categoryCodes.specificityRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.specificityRule must be a non-empty string.');
+  }
+  if (!hasNonEmptyString(categoryCodes.antiLeakageRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.antiLeakageRule must be a non-empty string that prevents the example cliches from being read as target aesthetics.');
+  }
+  if (!hasNonEmptyString(categoryCodes.selfTestRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.selfTestRule must be a non-empty string.');
+  }
+  if (!Array.isArray(categoryCodes.failingExamples) || categoryCodes.failingExamples.length < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.failingExamples must list at least 3 failing examples to anchor the specificity floor.');
+  }
+  if (!Array.isArray(categoryCodes.passingExamples) || categoryCodes.passingExamples.length < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.passingExamples must list at least 3 passing examples to anchor the specificity floor.');
+  }
+  if (!hasNonEmptyString(categoryCodes.passingExamplesPolicy)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.passingExamplesPolicy must be a non-empty string clarifying that the passing examples are description-format illustrations, not target aesthetics.');
+  }
+  if (!Array.isArray(categoryCodes.commonAiSafeClichesToReject) || categoryCodes.commonAiSafeClichesToReject.length < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.commonAiSafeClichesToReject must list at least 3 AI-safe defaults the agent has to name and reject when the project sits near them.');
+  }
+  if (!hasNonEmptyString(categoryCodes.commonAiSafeClichesPolicy)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.commonAiSafeClichesPolicy must be a non-empty string requiring the matching cliche to appear with a rejection note when the project pattern-matches it.');
+  }
+  if (
+    !Array.isArray(categoryCodes.requiredFieldsPerEntry)
+    || !categoryCodes.requiredFieldsPerEntry.includes('description')
+    || !categoryCodes.requiredFieldsPerEntry.includes('specificityEvidence')
+    || !categoryCodes.requiredFieldsPerEntry.includes('categoryDefaultReason')
+    || !categoryCodes.requiredFieldsPerEntry.includes('rejectionNote')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.requiredFieldsPerEntry must require description, specificityEvidence, categoryDefaultReason, and rejectionNote.');
+  }
+  if (!Array.isArray(categoryCodes.forbiddenPlaceholderPhrases) || categoryCodes.forbiddenPlaceholderPhrases.length === 0) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.forbiddenPlaceholderPhrases must list the abstract phrases that fail the specificity self-test.');
+  }
+  if (!Array.isArray(categoryCodes.candidateEntries)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.candidateEntries must be an array (empty in the seed; populated by the agent).');
+  }
+}
+
+function validateMorphologicalExploration(conceptualAnchor, validationErrors, options = {}) {
+  const { isSeedStatus = false } = options;
+  const morphologicalExploration = conceptualAnchor.morphologicalExploration;
+  if (!morphologicalExploration || typeof morphologicalExploration !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration must exist (Section 4 of research-design.md).');
+    return;
+  }
+  if (morphologicalExploration.mode !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.mode must equal "agent-must-complete-before-ui-implementation".');
+  }
+  if (morphologicalExploration.blockingByDefault !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.blockingByDefault must equal true.');
+  }
+  if (morphologicalExploration.researchBriefSection !== 'Section 4') {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.researchBriefSection must equal "Section 4".');
+  }
+  if (morphologicalExploration.requiredMatrixShape !== '5x5-or-6x5') {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.requiredMatrixShape must equal "5x5-or-6x5".');
+  }
+  if (morphologicalExploration.minimumDimensions !== 5) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.minimumDimensions must equal 5.');
+  }
+  if (morphologicalExploration.maximumDimensions !== 6) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.maximumDimensions must equal 6.');
+  }
+  if (morphologicalExploration.valuesPerDimension !== 5) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.valuesPerDimension must equal 5.');
+  }
+  if (morphologicalExploration.forbidCategoryCodeValuesInMatrix !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.forbidCategoryCodeValuesInMatrix must equal true so Section 3 cliches do not re-enter the matrix as values.');
+  }
+  if (morphologicalExploration.requireSelectedCombination !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.requireSelectedCombination must equal true.');
+  }
+  if (morphologicalExploration.requireUncomfortableCombination !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.requireUncomfortableCombination must equal true.');
+  }
+  if (!hasNonEmptyString(morphologicalExploration.uncomfortableCombinationRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombinationRule must be a non-empty string explaining why the uncomfortable combination is required.');
+  }
+  if (
+    !Array.isArray(morphologicalExploration.uncomfortableCombinationRequiredFields)
+    || !morphologicalExploration.uncomfortableCombinationRequiredFields.includes('combinationLabel')
+    || !morphologicalExploration.uncomfortableCombinationRequiredFields.includes('discomfortReason')
+    || !morphologicalExploration.uncomfortableCombinationRequiredFields.includes('productLogicJustification')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombinationRequiredFields must include combinationLabel, discomfortReason, and productLogicJustification.');
+  }
+  if (morphologicalExploration.widenDimensionsWhenUncomfortableCombinationCannotBeProduced !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.widenDimensionsWhenUncomfortableCombinationCannotBeProduced must equal true.');
+  }
+
+  if (morphologicalExploration.uncomfortableCombination !== null && typeof morphologicalExploration.uncomfortableCombination === 'object') {
+    const uncomfortableCombination = morphologicalExploration.uncomfortableCombination;
+    if (!hasNonEmptyString(uncomfortableCombination.combinationLabel)) {
+      validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombination.combinationLabel must be a non-empty string.');
+    }
+    if (!hasNonEmptyString(uncomfortableCombination.discomfortReason)) {
+      validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombination.discomfortReason must be a non-empty string.');
+    }
+    if (!hasNonEmptyString(uncomfortableCombination.productLogicJustification)) {
+      validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombination.productLogicJustification must be a non-empty string.');
+    }
+  }
+}
+
+function validateAnchorCandidates(conceptualAnchor, validationErrors, options = {}) {
+  const { isSeedStatus = false } = options;
+  const anchorCandidates = conceptualAnchor.anchorCandidates;
+  if (!anchorCandidates || typeof anchorCandidates !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates must exist (Section 5 of research-design.md).');
+    return;
+  }
+  if (anchorCandidates.mode !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.mode must equal "agent-must-complete-before-ui-implementation".');
+  }
+  if (anchorCandidates.blockingByDefault !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.blockingByDefault must equal true.');
+  }
+  if (anchorCandidates.researchBriefSection !== 'Section 5') {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.researchBriefSection must equal "Section 5".');
+  }
+  if (anchorCandidates.requiredCandidateCount !== 5) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.requiredCandidateCount must equal 5.');
+  }
+  if (
+    !Array.isArray(anchorCandidates.requiredFieldsPerCandidate)
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('anchorReference')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('jobFit')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('hierarchyImplication')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('densityImplication')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('typeImplication')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('stateLanguage')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('motionImplication')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('whatItRulesOut')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('renameTest')
+    || !anchorCandidates.requiredFieldsPerCandidate.includes('categoryCodeOverlap')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.requiredFieldsPerCandidate must list the full anchor dossier fields including renameTest and categoryCodeOverlap.');
+  }
+
+  const renameTest = anchorCandidates.renameTest;
+  if (!renameTest || typeof renameTest !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest must exist.');
+    return;
+  }
+  if (renameTest.mode !== 'strengthened') {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.mode must equal "strengthened".');
+  }
+  if (renameTest.requiredTestCategoryCount !== 3) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.requiredTestCategoryCount must equal 3.');
+  }
+  if (!hasNonEmptyString(renameTest.testCategoryDistanceRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.testCategoryDistanceRule must be a non-empty string requiring remote categories.');
+  }
+  if (!hasNonEmptyString(renameTest.testCategoryFreshnessRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.testCategoryFreshnessRule must be a non-empty string preventing reuse of the same test triple across every anchor.');
+  }
+  if (!renameTest.verdictScoring || typeof renameTest.verdictScoring !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.verdictScoring must define STRONG PASS, PASS, REVISE, and DISCARD verdicts.');
+  } else {
+    for (const verdict of ['STRONG PASS', 'PASS', 'REVISE', 'DISCARD']) {
+      if (!hasNonEmptyString(renameTest.verdictScoring[verdict])) {
+        validationErrors.push(`designIntent.conceptualAnchor.anchorCandidates.renameTest.verdictScoring["${verdict}"] must be a non-empty string.`);
+      }
+    }
+  }
+  if (renameTest.requireTestCategoriesRecordedInDossier !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.requireTestCategoriesRecordedInDossier must equal true.');
+  }
+  if (renameTest.auditableByHumanReviewer !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.auditableByHumanReviewer must equal true.');
+  }
+  if (
+    !Array.isArray(renameTest.renameTestRequiredFields)
+    || !renameTest.renameTestRequiredFields.includes('testCategories')
+    || !renameTest.renameTestRequiredFields.includes('results')
+    || !renameTest.renameTestRequiredFields.includes('verdict')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.renameTestRequiredFields must include testCategories, results, and verdict.');
+  }
+
+  if (!hasNonEmptyString(anchorCandidates.categoryCodeOverlapRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.categoryCodeOverlapRule must be a non-empty string.');
+  }
+  if (!Array.isArray(anchorCandidates.forbiddenSelectedVerdicts) || !anchorCandidates.forbiddenSelectedVerdicts.includes('DISCARD')) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.forbiddenSelectedVerdicts must include "DISCARD".');
+  }
+  if (
+    !Array.isArray(anchorCandidates.requiredSelectedVerdicts)
+    || !anchorCandidates.requiredSelectedVerdicts.includes('STRONG PASS')
+    || !anchorCandidates.requiredSelectedVerdicts.includes('PASS')
+  ) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.requiredSelectedVerdicts must include "STRONG PASS" and "PASS".');
+  }
+  if (!Array.isArray(anchorCandidates.candidates)) {
+    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.candidates must be an array (empty in the seed; populated by the agent).');
+  }
+}

package/lib/cli/project-scaffolder/design-contract/validation/audit-validators.mjs

@@ -0,0 +1,117 @@
+/**
+ * Validators for the AI-safe UI audit (with nested AI color and motion-spatial
+ * courage audits) and the production content policy. These are the gates that
+ * keep template-flavored UI from shipping by default.
+ */
+
+function validateAiColorAudit(aiSafeUiAudit, validationErrors) {
+  const aiColorAudit = aiSafeUiAudit.aiColorAudit;
+  if (!aiColorAudit || typeof aiColorAudit !== 'object') {
+    validationErrors.push('designIntent.aiSafeUiAudit.aiColorAudit must exist.');
+    return;
+  }
+  if (aiColorAudit.status !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.aiSafeUiAudit.aiColorAudit.status must require completion before UI implementation.');
+  }
+  if (!String(aiColorAudit.failureDefinition || '').includes('AI color')) {
+    validationErrors.push('designIntent.aiSafeUiAudit.aiColorAudit.failureDefinition must define AI color drift.');
+  }
+  if (!Array.isArray(aiColorAudit.autopilotRisks) || aiColorAudit.autopilotRisks.length < 4) {
+    validationErrors.push('designIntent.aiSafeUiAudit.aiColorAudit.autopilotRisks must list common autopilot palettes.');
+  }
+  if (!Array.isArray(aiColorAudit.requiredEvidence) || aiColorAudit.requiredEvidence.length < 3) {
+    validationErrors.push('designIntent.aiSafeUiAudit.aiColorAudit.requiredEvidence must list color evidence requirements.');
+  }
+  if (!String(aiColorAudit.reviewQuestion || '').trim()) {
+    validationErrors.push('designIntent.aiSafeUiAudit.aiColorAudit.reviewQuestion must be a non-empty string.');
+  }
+}
+
+function validateMotionSpatialCourageAudit(aiSafeUiAudit, validationErrors) {
+  const motionSpatialCourageAudit = aiSafeUiAudit.motionSpatialCourageAudit;
+  if (!motionSpatialCourageAudit || typeof motionSpatialCourageAudit !== 'object') {
+    validationErrors.push('designIntent.aiSafeUiAudit.motionSpatialCourageAudit must exist.');
+    return;
+  }
+  if (motionSpatialCourageAudit.status !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.aiSafeUiAudit.motionSpatialCourageAudit.status must require completion before UI implementation.');
+  }
+  if (!String(motionSpatialCourageAudit.defaultStance || '').includes('first-class options')) {
+    validationErrors.push('designIntent.aiSafeUiAudit.motionSpatialCourageAudit.defaultStance must treat motion and spatial UI as first-class options.');
+  }
+  if (!Array.isArray(motionSpatialCourageAudit.requiredDecisionFields) || motionSpatialCourageAudit.requiredDecisionFields.length < 3) {
+    validationErrors.push('designIntent.aiSafeUiAudit.motionSpatialCourageAudit.requiredDecisionFields must list required motion/spatial decisions.');
+  }
+  if (!String(motionSpatialCourageAudit.rejectionRule || '').includes('product reason')) {
+    validationErrors.push('designIntent.aiSafeUiAudit.motionSpatialCourageAudit.rejectionRule must require a product reason before omitting spatial UI.');
+  }
+  if (!String(motionSpatialCourageAudit.reviewQuestion || '').trim()) {
+    validationErrors.push('designIntent.aiSafeUiAudit.motionSpatialCourageAudit.reviewQuestion must be a non-empty string.');
+  }
+}
+
+export function validateAiSafeUiAudit(designIntentContract, validationErrors) {
+  if (!designIntentContract.aiSafeUiAudit || typeof designIntentContract.aiSafeUiAudit !== 'object') {
+    validationErrors.push('designIntent.aiSafeUiAudit must exist.');
+    return validationErrors;
+  }
+
+  const aiSafeUiAudit = designIntentContract.aiSafeUiAudit;
+  if (aiSafeUiAudit.status !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.aiSafeUiAudit.status must require completion before UI implementation.');
+  }
+  if (!String(aiSafeUiAudit.failureDefinition || '').includes('AI-safe')) {
+    validationErrors.push('designIntent.aiSafeUiAudit.failureDefinition must define AI-safe UI drift.');
+  }
+  if (!String(aiSafeUiAudit.failureDefinition || '').includes('placeholder copy')) {
+    validationErrors.push('designIntent.aiSafeUiAudit.failureDefinition must reject test/demo/placeholder UI copy.');
+  }
+  if (!String(aiSafeUiAudit.interchangeabilityTest || '').includes('renamed')) {
+    validationErrors.push('designIntent.aiSafeUiAudit.interchangeabilityTest must include the rename/interchangeability test.');
+  }
+  if (!Array.isArray(aiSafeUiAudit.requiredProductSpecificSignals) || aiSafeUiAudit.requiredProductSpecificSignals.length < 3) {
+    validationErrors.push('designIntent.aiSafeUiAudit.requiredProductSpecificSignals must list at least three product-specific signals.');
+  }
+  if (!String(aiSafeUiAudit.paletteExplorationRule || '').trim()) {
+    validationErrors.push('designIntent.aiSafeUiAudit.paletteExplorationRule must be a non-empty string.');
+  }
+  if (!String(aiSafeUiAudit.backgroundPatternRule || '').trim()) {
+    validationErrors.push('designIntent.aiSafeUiAudit.backgroundPatternRule must be a non-empty string.');
+  }
+
+  validateAiColorAudit(aiSafeUiAudit, validationErrors);
+  validateMotionSpatialCourageAudit(aiSafeUiAudit, validationErrors);
+
+  if (!String(aiSafeUiAudit.reviewQuestion || '').trim()) {
+    validationErrors.push('designIntent.aiSafeUiAudit.reviewQuestion must be a non-empty string.');
+  }
+  if (aiSafeUiAudit.blockingByDefault !== true) {
+    validationErrors.push('designIntent.aiSafeUiAudit.blockingByDefault must equal true.');
+  }
+  return validationErrors;
+}
+
+export function validateProductionContentPolicy(designIntentContract, validationErrors) {
+  if (!designIntentContract.productionContentPolicy || typeof designIntentContract.productionContentPolicy !== 'object') {
+    validationErrors.push('designIntent.productionContentPolicy must exist.');
+    return validationErrors;
+  }
+
+  const productionContentPolicy = designIntentContract.productionContentPolicy;
+  if (productionContentPolicy.status !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.productionContentPolicy.status must require completion before UI implementation.');
+  }
+  if (!String(productionContentPolicy.userFacingCopyRule || '').includes('testing')) {
+    validationErrors.push('designIntent.productionContentPolicy.userFacingCopyRule must reject testing/demo/placeholder UI copy.');
+  }
+  if (!String(productionContentPolicy.terminalDependencyRule || '').includes('Terminal commands')) {
+    validationErrors.push('designIntent.productionContentPolicy.terminalDependencyRule must keep terminal commands out of core UI flows.');
+  }
+  if (!Array.isArray(productionContentPolicy.allowedExceptions) || productionContentPolicy.allowedExceptions.length < 3) {
+    validationErrors.push('designIntent.productionContentPolicy.allowedExceptions must list limited exceptions.');
+  }
+  if (productionContentPolicy.blockingByDefault !== true) {
+    validationErrors.push('designIntent.productionContentPolicy.blockingByDefault must equal true.');
+  }
+  return validationErrors;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Completeness check for the design intent contract: validates the conceptual
+ * anchor reference, derived token logic shape, library research status, and
+ * library decision entries. Used both standalone (for incremental seeds) and
+ * as the first stage of `validateDesignIntentContract`.
+ */
+
+import { hasNonEmptyString } from './helpers.mjs';
+
+export function validateDesignContractCompleteness(designIntentContract) {
+  const validationIssues = [];
+  const conceptualAnchor = designIntentContract?.conceptualAnchor;
+  const derivedTokenLogic = designIntentContract?.derivedTokenLogic;
+  const libraryDecisions = designIntentContract?.libraryDecisions;
+
+  const anchorReference = conceptualAnchor?.anchorReference || derivedTokenLogic?.anchorReference;
+  if (!hasNonEmptyString(anchorReference)) {
+    validationIssues.push('designIntent.conceptualAnchor.anchorReference must be a stable non-empty ID for deterministic validation.');
+  }
+
+  if (!derivedTokenLogic || typeof derivedTokenLogic !== 'object') {
+    validationIssues.push('designIntent.derivedTokenLogic must exist.');
+  } else {
+    if (derivedTokenLogic.anchorReference !== anchorReference) {
+      validationIssues.push('designIntent.derivedTokenLogic.anchorReference must exactly match designIntent.conceptualAnchor.anchorReference.');
+    }
+
+    for (const requiredFieldName of [
+      'colorDerivationSource',
+      'spacingDerivationSource',
+      'typographyDerivationSource',
+      'motionDerivationSource',
+      'colorSpace',
+      'spatialBaseUnit',
+      'typeScaleMethod',
+      'motionBudget',
+      'validationRule',
+    ]) {
+      if (!hasNonEmptyString(derivedTokenLogic[requiredFieldName])) {
+        validationIssues.push(`designIntent.derivedTokenLogic.${requiredFieldName} must be a non-empty string.`);
+      }
+    }
+
+    if (
+      hasNonEmptyString(derivedTokenLogic.validationRule)
+      && !derivedTokenLogic.validationRule.includes('anchorReference')
+    ) {
+      validationIssues.push('designIntent.derivedTokenLogic.validationRule must require traceability to anchorReference.');
+    }
+  }
+
+  if (!['verified', 'pending-verification', 'no-external-library-needed'].includes(designIntentContract?.libraryResearchStatus)) {
+    validationIssues.push('designIntent.libraryResearchStatus must be verified, pending-verification, or no-external-library-needed.');
+  }
+
+  if (!Array.isArray(libraryDecisions)) {
+    validationIssues.push('designIntent.libraryDecisions must be an array.');
+  } else {
+    for (const [libraryIndex, libraryDecision] of libraryDecisions.entries()) {
+      if (!libraryDecision || typeof libraryDecision !== 'object') {
+        validationIssues.push(`designIntent.libraryDecisions[${libraryIndex}] must be an object.`);
+        continue;
+      }
+
+      if (!hasNonEmptyString(libraryDecision.library)) {
+        validationIssues.push(`designIntent.libraryDecisions[${libraryIndex}].library must be a non-empty string.`);
+      }
+      if (!hasNonEmptyString(libraryDecision.purpose)) {
+        validationIssues.push(`designIntent.libraryDecisions[${libraryIndex}].purpose must be a non-empty string.`);
+      }
+
+      const hasVerification = hasNonEmptyString(libraryDecision.verifiedAt)
+        && hasNonEmptyString(libraryDecision.sourceUrl);
+      const hasFallback = hasNonEmptyString(libraryDecision.fallbackIfUnavailable);
+
+      if (!hasVerification && !hasFallback) {
+        validationIssues.push(`designIntent.libraryDecisions[${libraryIndex}] must either record verification source or provide fallbackIfUnavailable.`);
+      }
+    }
+  }
+
+  return validationIssues;
+}