@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

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

@@ -0,0 +1,328 @@
+/**
+ * Validators for the design execution policy, the structured execution
+ * handoff, the review rubric, the required design sections list, and the
+ * forbidden patterns list. These collectively gate the structured handoff
+ * payload that downstream UI judges and review tooling consume.
+ */
+
+import { hasNonEmptyString } from './helpers.mjs';
+import { DESIGN_REQUIRED_SECTIONS } from '../../constants.mjs';
+
+export function validateDesignExecutionPolicy(designIntentContract, validationErrors) {
+  if (!designIntentContract.designExecutionPolicy || typeof designIntentContract.designExecutionPolicy !== 'object') {
+    validationErrors.push('designIntent.designExecutionPolicy must exist.');
+    return validationErrors;
+  }
+  const designExecutionPolicy = designIntentContract.designExecutionPolicy;
+  if (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',
+    'requireCreativeCommitmentGate',
+    'requireStructuredHandoff',
+    'requireRepoEvidenceAlignment',
+    'forbidScreenshotDependency',
+    'separateRequiredOutcomesFromCandidateMoves',
+    'forbidCandidateMovesAsLockedRequirements',
+    'forbidLibraryThemeAsVisualAuthority',
+    'forbidLiteralAnchorChromeWithoutProductFunction',
+    'requirePerSurfaceMutationOps',
+    'forbidUniformSiblingSurfaceTreatment',
+    'zeroBasedRedesignResetsPriorVisualsWhenRequested',
+  ]) {
+    if (designExecutionPolicy[requiredFlagName] !== true) {
+      validationErrors.push(`designIntent.designExecutionPolicy.${requiredFlagName} must equal true.`);
+    }
+  }
+  if (designExecutionPolicy.handoffFormatVersion !== 'ui-handoff-v1') {
+    validationErrors.push('designIntent.designExecutionPolicy.handoffFormatVersion must equal "ui-handoff-v1".');
+  }
+  if (
+    !Array.isArray(designExecutionPolicy.semanticReviewFocus)
+    || designExecutionPolicy.semanticReviewFocus.length < 4
+  ) {
+    validationErrors.push('designIntent.designExecutionPolicy.semanticReviewFocus must list the required review dimensions.');
+  }
+  return validationErrors;
+}
+
+function validateHandoffComponentGraph(designExecutionHandoff, validationErrors) {
+  const componentGraph = designExecutionHandoff.componentGraph;
+  if (!componentGraph || typeof componentGraph !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff.componentGraph must exist.');
+    return;
+  }
+  if (!Array.isArray(componentGraph.nodes) || componentGraph.nodes.length < 2) {
+    validationErrors.push('designIntent.designExecutionHandoff.componentGraph.nodes must list the primary execution nodes.');
+  }
+  if (!Array.isArray(componentGraph.edges) || componentGraph.edges.length < 1) {
+    validationErrors.push('designIntent.designExecutionHandoff.componentGraph.edges must define relationships between UI nodes.');
+  }
+}
+
+function validateHandoffContentPriorityMap(designExecutionHandoff, validationErrors) {
+  const contentPriorityMap = designExecutionHandoff.contentPriorityMap;
+  if (!contentPriorityMap || typeof contentPriorityMap !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff.contentPriorityMap must exist.');
+    return;
+  }
+  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.`);
+    }
+  }
+}
+
+function validateHandoffViewportMutationPlan(designExecutionHandoff, validationErrors) {
+  const viewportMutationPlan = designExecutionHandoff.viewportMutationPlan;
+  if (!viewportMutationPlan || typeof viewportMutationPlan !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff.viewportMutationPlan must exist.');
+    return;
+  }
+  for (const viewportKey of ['mobile', 'tablet', 'desktop']) {
+    const viewportPlan = viewportMutationPlan[viewportKey];
+    if (!viewportPlan || typeof viewportPlan !== 'object') {
+      validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey} must be an object.`);
+      continue;
+    }
+    if (!String(viewportPlan.primaryOperation || '').trim()) {
+      validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.primaryOperation must be a non-empty string.`);
+    }
+    if (!Array.isArray(viewportPlan.requiredSurfaceActions) || viewportPlan.requiredSurfaceActions.length < 2) {
+      validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.requiredSurfaceActions must contain at least two actions.`);
+    }
+    if (!Array.isArray(viewportPlan.forbiddenPatterns) || viewportPlan.forbiddenPatterns.length < 1) {
+      validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.forbiddenPatterns must contain at least one anti-pattern.`);
+    }
+    if (!String(viewportPlan.rationale || '').trim()) {
+      validationErrors.push(`designIntent.designExecutionHandoff.viewportMutationPlan.${viewportKey}.rationale must be a non-empty string.`);
+    }
+  }
+}
+
+function validateHandoffExpressionFlexibility(designExecutionHandoff, validationErrors) {
+  const expressionFlexibility = designExecutionHandoff.expressionFlexibility;
+  if (!expressionFlexibility || typeof expressionFlexibility !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility must exist.');
+    return;
+  }
+  if (!Array.isArray(expressionFlexibility.lockedOutcomes) || expressionFlexibility.lockedOutcomes.length < 3) {
+    validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.lockedOutcomes must list locked outcomes.');
+  }
+  if (!Array.isArray(expressionFlexibility.candidateSignatureMoves) || expressionFlexibility.candidateSignatureMoves.length < 1) {
+    validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.candidateSignatureMoves must include at least one candidate move placeholder.');
+  }
+  if (!Array.isArray(expressionFlexibility.flexibleAxes) || expressionFlexibility.flexibleAxes.length < 4) {
+    validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.flexibleAxes must list flexible implementation axes.');
+  }
+  if (!String(expressionFlexibility.lockingRule || '').includes('candidate')) {
+    validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.lockingRule must explain when candidate moves become required.');
+  }
+}
+
+function validateHandoffCreativeCommitment(designExecutionHandoff, validationErrors) {
+  const creativeCommitment = designExecutionHandoff.creativeCommitment;
+  if (!creativeCommitment || typeof creativeCommitment !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff.creativeCommitment must exist.');
+    return;
+  }
+  if (creativeCommitment.status !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.designExecutionHandoff.creativeCommitment.status must equal "agent-must-complete-before-ui-implementation".');
+  }
+  if (
+    !Array.isArray(creativeCommitment.requiredFields)
+    || !creativeCommitment.requiredFields.includes('specificReferencePoint')
+    || !creativeCommitment.requiredFields.includes('signatureMotion')
+    || !creativeCommitment.requiredFields.includes('typographicDecision')
+  ) {
+    validationErrors.push('designIntent.designExecutionHandoff.creativeCommitment.requiredFields must include specificReferencePoint, signatureMotion, and typographicDecision.');
+  }
+  if (!hasNonEmptyString(creativeCommitment.failureMode)) {
+    validationErrors.push('designIntent.designExecutionHandoff.creativeCommitment.failureMode must be a non-empty string.');
+  }
+}
+
+function validateHandoffImplementationGuardrails(designExecutionHandoff, validationErrors) {
+  const implementationGuardrails = designExecutionHandoff.implementationGuardrails;
+  if (!implementationGuardrails || typeof implementationGuardrails !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff.implementationGuardrails must exist.');
+    return;
+  }
+  for (const requiredFlagName of [
+    'requireBuildFromHandoff',
+    'requireGapNotesBeforeFallback',
+    'forbidGenericLayoutFallbackWithoutReason',
+    'requireLockedVsFlexibleDecisionReview',
+    'forbidCandidateMoveHardcoding',
+    'forbidTestingDemoCopyInUi',
+    'forbidTerminalOnlyUserFlows',
+  ]) {
+    if (implementationGuardrails[requiredFlagName] !== true) {
+      validationErrors.push(`designIntent.designExecutionHandoff.implementationGuardrails.${requiredFlagName} must equal true.`);
+    }
+  }
+}
+
+export function validateDesignExecutionHandoff(designIntentContract, validationErrors) {
+  if (!designIntentContract.designExecutionHandoff || typeof designIntentContract.designExecutionHandoff !== 'object') {
+    validationErrors.push('designIntent.designExecutionHandoff must exist.');
+    return validationErrors;
+  }
+
+  const designExecutionHandoff = designIntentContract.designExecutionHandoff;
+  if (designExecutionHandoff.version !== 'ui-handoff-v1') {
+    validationErrors.push('designIntent.designExecutionHandoff.version must equal "ui-handoff-v1".');
+  }
+  if (designExecutionHandoff.seedMode !== 'structure-first-scaffold') {
+    validationErrors.push('designIntent.designExecutionHandoff.seedMode must equal "structure-first-scaffold".');
+  }
+  if (designExecutionHandoff.requiresTaskSpecificRefinement !== true) {
+    validationErrors.push('designIntent.designExecutionHandoff.requiresTaskSpecificRefinement must equal true.');
+  }
+  if (!String(designExecutionHandoff.primaryExperienceGoal || '').trim()) {
+    validationErrors.push('designIntent.designExecutionHandoff.primaryExperienceGoal must be a non-empty string.');
+  }
+  if (!Array.isArray(designExecutionHandoff.surfacePlan) || designExecutionHandoff.surfacePlan.length < 1) {
+    validationErrors.push('designIntent.designExecutionHandoff.surfacePlan must define at least one planned surface.');
+  }
+
+  validateHandoffComponentGraph(designExecutionHandoff, validationErrors);
+  validateHandoffContentPriorityMap(designExecutionHandoff, validationErrors);
+  validateHandoffViewportMutationPlan(designExecutionHandoff, validationErrors);
+
+  if (!Array.isArray(designExecutionHandoff.interactionStateMatrix) || designExecutionHandoff.interactionStateMatrix.length < 1) {
+    validationErrors.push('designIntent.designExecutionHandoff.interactionStateMatrix must list key component state expectations.');
+  }
+
+  validateHandoffExpressionFlexibility(designExecutionHandoff, validationErrors);
+
+  if (!Array.isArray(designExecutionHandoff.taskFlowNarrative) || designExecutionHandoff.taskFlowNarrative.length < 2) {
+    validationErrors.push('designIntent.designExecutionHandoff.taskFlowNarrative must describe the key UI task flow in sequence.');
+  }
+  if (!String(designExecutionHandoff.signatureMoveRationale || '').trim()) {
+    validationErrors.push('designIntent.designExecutionHandoff.signatureMoveRationale must explain the chosen authored move.');
+  }
+
+  validateHandoffCreativeCommitment(designExecutionHandoff, validationErrors);
+  validateHandoffImplementationGuardrails(designExecutionHandoff, validationErrors);
+  return validationErrors;
+}
+
+export function validateReviewRubric(designIntentContract, validationErrors) {
+  if (!designIntentContract.reviewRubric || typeof designIntentContract.reviewRubric !== 'object') {
+    validationErrors.push('designIntent.reviewRubric must exist.');
+    return validationErrors;
+  }
+  const reviewRubric = designIntentContract.reviewRubric;
+  if (reviewRubric.version !== 'ui-rubric-v1') {
+    validationErrors.push('designIntent.reviewRubric.version must equal "ui-rubric-v1".');
+  }
+  if (reviewRubric.genericityAutoFail !== true) {
+    validationErrors.push('designIntent.reviewRubric.genericityAutoFail must equal true.');
+  }
+  if (!Array.isArray(reviewRubric.dimensions) || reviewRubric.dimensions.length < 5) {
+    validationErrors.push('designIntent.reviewRubric.dimensions must define the required rubric dimensions.');
+  } else {
+    for (const requiredRubricKey of [
+      'distinctiveness',
+      'contractFidelity',
+      'visualConsistency',
+      'heuristicUxQuality',
+      'motionDiscipline',
+    ]) {
+      if (!reviewRubric.dimensions.some((dimension) => dimension?.key === requiredRubricKey)) {
+        validationErrors.push(`designIntent.reviewRubric.dimensions is missing "${requiredRubricKey}".`);
+      }
+    }
+  }
+  if (!Array.isArray(reviewRubric.genericitySignals) || reviewRubric.genericitySignals.length < 3) {
+    validationErrors.push('designIntent.reviewRubric.genericitySignals must list common genericity drift signals.');
+  } else {
+    for (const requiredSignal of [
+      'ai-safe-ui-template-look',
+      'ai-color-default-palette-without-product-role-behavior',
+      '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',
+      'motion-or-3d-omitted-from-fear-without-fit-analysis',
+    ]) {
+      if (!reviewRubric.genericitySignals.includes(requiredSignal)) {
+        validationErrors.push(`designIntent.reviewRubric.genericitySignals must include "${requiredSignal}".`);
+      }
+    }
+  }
+  if (!Array.isArray(reviewRubric.validBoldSignals) || reviewRubric.validBoldSignals.length < 3) {
+    validationErrors.push('designIntent.reviewRubric.validBoldSignals must list legitimate authored signals.');
+  } else {
+    for (const requiredSignal of [
+      'three-at-a-glance-product-specific-signals',
+      'visually-exploratory-accessible-palette-derived-from-product',
+      'audacious-accessible-palette-with-product-role-behavior',
+      'motion-or-spatial-experience-derived-from-anchor',
+    ]) {
+      if (!reviewRubric.validBoldSignals.includes(requiredSignal)) {
+        validationErrors.push(`designIntent.reviewRubric.validBoldSignals must include "${requiredSignal}".`);
+      }
+    }
+  }
+  if (!reviewRubric.reportingRules || typeof reviewRubric.reportingRules !== 'object') {
+    validationErrors.push('designIntent.reviewRubric.reportingRules must exist.');
+    return validationErrors;
+  }
+  for (const requiredFlagName of [
+    'mustExplainGenericity',
+    'mustSeparateTasteFromFailure',
+    'contractFidelityOverridesPersonalTaste',
+  ]) {
+    if (reviewRubric.reportingRules[requiredFlagName] !== true) {
+      validationErrors.push(`designIntent.reviewRubric.reportingRules.${requiredFlagName} must equal true.`);
+    }
+  }
+  return validationErrors;
+}
+
+export function validateRequiredSectionsAndForbiddenPatterns(designIntentContract, validationErrors) {
+  if (
+    !Array.isArray(designIntentContract.requiredDesignSections)
+    || designIntentContract.requiredDesignSections.length !== DESIGN_REQUIRED_SECTIONS.length
+  ) {
+    validationErrors.push('designIntent.requiredDesignSections must match the required design contract sections.');
+  } else {
+    for (const requiredSectionName of DESIGN_REQUIRED_SECTIONS) {
+      if (!designIntentContract.requiredDesignSections.includes(requiredSectionName)) {
+        validationErrors.push(`designIntent.requiredDesignSections is missing "${requiredSectionName}".`);
+      }
+    }
+  }
+
+  if (!Array.isArray(designIntentContract.forbiddenPatterns) || designIntentContract.forbiddenPatterns.length < 4) {
+    validationErrors.push('designIntent.forbiddenPatterns must list concrete anti-generic patterns.');
+    return validationErrors;
+  }
+  for (const requiredPattern of [
+    'ai-safe-ui-template-look',
+    'ai-color-default-palette-without-product-role-behavior',
+    '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',
+    'motion-or-3d-omitted-from-fear-without-fit-analysis',
+  ]) {
+    if (!designIntentContract.forbiddenPatterns.includes(requiredPattern)) {
+      validationErrors.push(`designIntent.forbiddenPatterns must include "${requiredPattern}".`);
+    }
+  }
+  return validationErrors;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Tiny validator helpers shared across the design contract validation
+ * sub-modules. Pure, side-effect free.
+ */
+
+export function hasNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Research dossier validators. Enforces the `researchDossier.metadata` block
+ * shape that powers the freshness gate, status-aware skip, and anti-repeat
+ * ledger consumed by `.agent-context/prompts/research-design.md`.
+ */
+
+import { hasNonEmptyString } from './helpers.mjs';
+
+const REQUIRED_FRESHNESS_WINDOW_DAYS = 90;
+const REQUIRED_SEED_STATUSES = [
+  'seed-needs-design-synthesis',
+  'seed-generated-during-init',
+  'seed-generated-during-upgrade',
+];
+const ANTI_REPEAT_LEDGER_CATEGORIES = ['previousAnchors', 'previousPalettes', 'previousMotionSignatures'];
+
+function validateMetadataBaseShape(metadata, validationErrors) {
+  if (
+    metadata.researchVerifiedAt !== null
+    && (typeof metadata.researchVerifiedAt !== 'string' || metadata.researchVerifiedAt.trim().length === 0)
+  ) {
+    validationErrors.push('designIntent.researchDossier.metadata.researchVerifiedAt must be null or an ISO date string.');
+  }
+  if (!Number.isInteger(metadata.freshnessWindowDays) || metadata.freshnessWindowDays < 1) {
+    validationErrors.push(`designIntent.researchDossier.metadata.freshnessWindowDays must be a positive integer (recommended ${REQUIRED_FRESHNESS_WINDOW_DAYS}).`);
+  }
+  if (!hasNonEmptyString(metadata.freshnessRule)) {
+    validationErrors.push('designIntent.researchDossier.metadata.freshnessRule must be a non-empty string explaining staleness.');
+  }
+  if (metadata.userExplicitRedesignBypassesFreshness !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.userExplicitRedesignBypassesFreshness must equal true so explicit redesign requests force fresh research.');
+  }
+}
+
+function validateStatusAwareValidation(metadata, validationErrors) {
+  const statusAwareValidation = metadata.statusAwareValidation;
+  if (!statusAwareValidation || typeof statusAwareValidation !== 'object') {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation must exist.');
+    return;
+  }
+  const seedStatuses = statusAwareValidation.seedStatuses;
+  const hasAllRequiredSeedStatuses = Array.isArray(seedStatuses)
+    && REQUIRED_SEED_STATUSES.every((requiredSeedStatusName) => seedStatuses.includes(requiredSeedStatusName));
+  if (!hasAllRequiredSeedStatuses) {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation.seedStatuses must include seed-needs-design-synthesis, seed-generated-during-init, and seed-generated-during-upgrade.');
+  }
+  if (statusAwareValidation.seedSkipsDossierShape !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation.seedSkipsDossierShape must equal true.');
+  }
+  if (statusAwareValidation.activeRequiresFreshOrExplicitRedesign !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation.activeRequiresFreshOrExplicitRedesign must equal true.');
+  }
+}
+
+function validateAntiRepeatLedger(metadata, validationErrors) {
+  const antiRepeatLedger = metadata.antiRepeatLedger;
+  if (!antiRepeatLedger || typeof antiRepeatLedger !== 'object') {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger must exist.');
+    return;
+  }
+  if (antiRepeatLedger.blocklistFromHistory !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger.blocklistFromHistory must equal true so previously shipped direction is blocked from repetition.');
+  }
+  if (antiRepeatLedger.ledgerScope !== 'signature-level-descriptors-only') {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger.ledgerScope must equal "signature-level-descriptors-only" so the ledger does not become a raw token dump.');
+  }
+  if (
+    !Number.isInteger(antiRepeatLedger.ledgerMaxEntriesPerCategory)
+    || antiRepeatLedger.ledgerMaxEntriesPerCategory < 1
+    || antiRepeatLedger.ledgerMaxEntriesPerCategory > 5
+  ) {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory must be an integer between 1 and 5 to keep the ledger signature-level.');
+  }
+  for (const ledgerCategoryName of ANTI_REPEAT_LEDGER_CATEGORIES) {
+    const ledgerEntries = antiRepeatLedger[ledgerCategoryName];
+    if (!Array.isArray(ledgerEntries)) {
+      validationErrors.push(`designIntent.researchDossier.metadata.antiRepeatLedger.${ledgerCategoryName} must be an array (may be empty in fresh seeds).`);
+      continue;
+    }
+    if (
+      Number.isInteger(antiRepeatLedger.ledgerMaxEntriesPerCategory)
+      && ledgerEntries.length > antiRepeatLedger.ledgerMaxEntriesPerCategory
+    ) {
+      validationErrors.push(`designIntent.researchDossier.metadata.antiRepeatLedger.${ledgerCategoryName} exceeds ledgerMaxEntriesPerCategory; trim to signature-level descriptors.`);
+    }
+  }
+}
+
+export function validateResearchDossier(designIntentContract, validationErrors) {
+  const researchDossier = designIntentContract?.researchDossier;
+  if (!researchDossier || typeof researchDossier !== 'object') {
+    validationErrors.push('designIntent.researchDossier must exist (Section 3-5 metadata block from research-design.md).');
+    return validationErrors;
+  }
+  const metadata = researchDossier.metadata;
+  if (!metadata || typeof metadata !== 'object') {
+    validationErrors.push('designIntent.researchDossier.metadata must exist with researchVerifiedAt, freshnessWindowDays, and antiRepeatLedger.');
+    return validationErrors;
+  }
+  validateMetadataBaseShape(metadata, validationErrors);
+  validateStatusAwareValidation(metadata, validationErrors);
+  validateAntiRepeatLedger(metadata, validationErrors);
+  return validationErrors;
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Structural-shape validators for the design intent contract: top-level mode,
+ * project block, design philosophy, external research intake, and the design
+ * flexibility policy. Each validator pushes its findings onto the shared error
+ * accumulator and returns it.
+ */
+
+import { hasNonEmptyString } from './helpers.mjs';
+
+export function validateModeAndProjectShape(designIntentContract, validationErrors) {
+  if (designIntentContract.mode !== 'dynamic') {
+    validationErrors.push('designIntent.mode must equal "dynamic".');
+  }
+
+  if (!designIntentContract.project || typeof designIntentContract.project !== 'object') {
+    validationErrors.push('designIntent.project must exist.');
+  }
+
+  if (!designIntentContract.designPhilosophy || typeof designIntentContract.designPhilosophy !== 'string') {
+    validationErrors.push('designIntent.designPhilosophy must be a non-empty string.');
+  }
+  return validationErrors;
+}
+
+export function validateExternalResearchIntake(designIntentContract, validationErrors) {
+  if (!designIntentContract.externalResearchIntake || typeof designIntentContract.externalResearchIntake !== 'object') {
+    validationErrors.push('designIntent.externalResearchIntake must exist.');
+    return validationErrors;
+  }
+
+  const externalResearchIntake = designIntentContract.externalResearchIntake;
+  if (externalResearchIntake.userSuppliedResearchPolicy !== 'read-as-candidate-evidence-not-final-prescription') {
+    validationErrors.push('designIntent.externalResearchIntake.userSuppliedResearchPolicy must preserve user research as candidate evidence.');
+  }
+  if (externalResearchIntake.requireOfficialDocsVerificationForTechnologyClaims !== true) {
+    validationErrors.push('designIntent.externalResearchIntake.requireOfficialDocsVerificationForTechnologyClaims must equal true.');
+  }
+  if (
+    !Array.isArray(externalResearchIntake.candidateDomains)
+    || !externalResearchIntake.candidateDomains.includes('motion-and-scroll')
+  ) {
+    validationErrors.push('designIntent.externalResearchIntake.candidateDomains must include motion-and-scroll.');
+  }
+  return validationErrors;
+}
+
+export function validateDesignFlexibilityPolicy(designIntentContract, validationErrors) {
+  if (!designIntentContract.designFlexibilityPolicy || typeof designIntentContract.designFlexibilityPolicy !== 'object') {
+    validationErrors.push('designIntent.designFlexibilityPolicy must exist.');
+    return validationErrors;
+  }
+
+  const designFlexibilityPolicy = designIntentContract.designFlexibilityPolicy;
+  if (designFlexibilityPolicy.mode !== 'locked-outcomes-flexible-expression') {
+    validationErrors.push('designIntent.designFlexibilityPolicy.mode must equal "locked-outcomes-flexible-expression".');
+  }
+  if (!hasNonEmptyString(designFlexibilityPolicy.contractRole)) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.contractRole must be a non-empty string.');
+  }
+  if (!Array.isArray(designFlexibilityPolicy.lockedOutcomeTypes) || designFlexibilityPolicy.lockedOutcomeTypes.length < 4) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.lockedOutcomeTypes must list the locked outcome categories.');
+  }
+  if (!Array.isArray(designFlexibilityPolicy.flexibleExpressionAxes) || designFlexibilityPolicy.flexibleExpressionAxes.length < 4) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.flexibleExpressionAxes must list flexible expression axes.');
+  }
+  if (!hasNonEmptyString(designFlexibilityPolicy.tokenLockingRule)) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.tokenLockingRule must be a non-empty string.');
+  }
+  if (!String(designFlexibilityPolicy.signatureMovePolicy || '').includes('candidate')) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.signatureMovePolicy must separate candidate moves from required outcomes.');
+  }
+  if (!String(designFlexibilityPolicy.libraryVisualLanguagePolicy || '').includes('Libraries supply')) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.libraryVisualLanguagePolicy must keep libraries from dictating visual language.');
+  }
+  if (!String(designFlexibilityPolicy.literalAnchorPolicy || '').includes('Translate anchors')) {
+    validationErrors.push('designIntent.designFlexibilityPolicy.literalAnchorPolicy must require non-literal anchor translation.');
+  }
+  return validationErrors;
+}