@ryuenn3123/agentic-senior-core 4.0.0 → 4.0.2

package/lib/cli/project-scaffolder/design-contract/sections/conceptual-anchor.mjs

@@ -2,6 +2,12 @@
  * Conceptual anchor section of the design intent contract. Encodes the rules
  * that force agents to commit to a real-world reference, motion, and typography
  * decision before UI implementation, instead of defaulting to spatial cliches.
+ *
+ * Carries the Section 3-5 dossier from
+ * `.agent-context/prompts/research-design.md`:
+ *   - categoryCodes (Section 3)
+ *   - morphologicalExploration (Section 4)
+ *   - anchorCandidates (Section 5)
  */
 
 export function buildConceptualAnchorSection() {
@@ -9,6 +15,7 @@ export function buildConceptualAnchorSection() {
     mode: 'required-when-no-external-research',
     seedMode: 'selection-policy-only',
     anchorReference: 'agent-defined-anchor-reference',
+    researchBrief: '.agent-context/prompts/research-design.md',
     requiresAgentSelectionBeforeUiImplementation: true,
     userResearchAbsencePolicy: {
       userSuppliedResearchOnly: true,
@@ -88,6 +95,116 @@ export function buildConceptualAnchorSection() {
       'motion',
       'responsive-composition',
     ],
+    categoryCodes: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 3',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      minimumEntries: 3,
+      specificityRule: 'A category code is only valid if a reader unfamiliar with the project can visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name.',
+      antiLeakageRule: 'Listing a cliche identifies a trap; it does not endorse an aesthetic. Examples in the brief are NOT target aesthetics for any project. Each category code must carry an explicit rejection note so the cliche cannot quietly become the target.',
+      failingExamples: [
+        'clean typography (too abstract, applies to anything)',
+        'modern color palette (not falsifiable)',
+        'smooth animations (describes nothing specific)',
+      ],
+      passingExamples: [
+        "children's storybook illustration site: hand-painted gouache textures with irregular hand-lettered titles, off-grid spreads with whitespace gutters, page-turn pacing rather than scroll (instantly recognizable as kids book category default)",
+        'luxury car configurator: full-bleed monochrome photography on black, ultra-thin sans-serif tracked wide, slow horizontal scroll with locked vertical alignment, micro-counters that tick instead of slide (instantly recognizable as luxury auto category default)',
+        'academic philosophy journal: high-contrast black-on-cream, book-class serif body at 11pt with generous leading, footnote markers with hover panels, numbered table-of-contents navigation, no hero imagery (instantly recognizable as academic journal category default)',
+      ],
+      passingExamplesPolicy: 'These examples illustrate the description format only. They are AI-defaultable cliches of their categories and must NOT be adopted as target aesthetics for any project.',
+      commonAiSafeClichesToReject: [
+        'dev-tool default: condensed tabular numerics with minimal chrome and monospace code blocks on dark slate background, sans-serif metadata at 11-12px, monochrome status dots, single-line settings rows',
+        'AI-startup landing default: purple-to-pink gradient hero with floating 3D glass cards, sans-serif display type at 700-900 weight, vague hero copy, three-up feature grid below the fold',
+        'health/wellness app default: mint accent on white surface with coral status indicators, rounded pill-shaped buttons, friendly sans-serif at high weight, soft drop shadows on cards',
+        'SaaS admin default: left-side icon-only nav, top utility bar, three-card KPI row above a single data table, neutral grey-on-white with one accent color, modal-driven detail flows',
+        'marketing site default: hero image with one-line headline plus subhead, three feature tiles below, two pricing tiers, testimonial carousel, footer link grid',
+      ],
+      commonAiSafeClichesPolicy: 'If the project sits anywhere near one of these AI-safe defaults, the matching cliche must appear in candidateEntries with an explicit rejection note. Software products pattern-match one of these without intervention; naming the trap is required even when the trap is uncomfortable to admit.',
+      selfTestRule: 'Read each category code aloud to someone unfamiliar with the project. If they cannot visualize a specific aesthetic direction from the text alone, the code is too abstract; revise. If they say "that is basically the X cliche", the description is specific enough; the cliche then belongs on the reject list with a rejection note, not as a candidate target.',
+      requiredFieldsPerEntry: [
+        'description',
+        'specificityEvidence',
+        'categoryDefaultReason',
+        'rejectionNote',
+      ],
+      forbiddenPlaceholderPhrases: [
+        'clean typography',
+        'modern color palette',
+        'smooth animations',
+        'best practices',
+        'good design',
+      ],
+      candidateEntries: [],
+    },
+    morphologicalExploration: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 4',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      requiredMatrixShape: '5x5-or-6x5',
+      minimumDimensions: 5,
+      maximumDimensions: 6,
+      valuesPerDimension: 5,
+      forbidCategoryCodeValuesInMatrix: true,
+      requireSelectedCombination: true,
+      requireUncomfortableCombination: true,
+      uncomfortableCombinationRule: 'Highlight at least one combination that feels instinctively wrong or uncomfortable but can be argued with product logic. The uncomfortable combination proves the matrix actually spans the design space; if every combination feels safe, shippable, and unobjectionable, the matrix is clustering in the safe-creative zone.',
+      uncomfortableCombinationRequiredFields: [
+        'combinationLabel',
+        'discomfortReason',
+        'productLogicJustification',
+      ],
+      widenDimensionsWhenUncomfortableCombinationCannotBeProduced: true,
+      seedDimensions: [],
+      seedMatrix: [],
+      selectedCombination: null,
+      uncomfortableCombination: null,
+    },
+    anchorCandidates: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 5',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      requiredCandidateCount: 5,
+      requiredFieldsPerCandidate: [
+        'anchorReference',
+        'conceptualFamily',
+        'jobFit',
+        'hierarchyImplication',
+        'densityImplication',
+        'typeImplication',
+        'stateLanguage',
+        'motionImplication',
+        'whatItRulesOut',
+        'renameTest',
+        'categoryCodeOverlap',
+      ],
+      renameTest: {
+        mode: 'strengthened',
+        requiredTestCategoryCount: 3,
+        testCategoryDistanceRule: 'The three test categories must be remote from each other and from the actual product (for example, if the product is a health app, test against fintech dashboard, kids educational game, and industrial equipment monitoring console).',
+        testCategoryFreshnessRule: 'Pick fresh test categories per anchor. Reusing the same triple across every anchor lets the agent memorize the pass condition instead of stress-testing the anchor. The illustrative triple in testCategoryDistanceRule is not a fixed test set.',
+        verdictScoring: {
+          'STRONG PASS': 'UI still coherent in 0 of 3 renamed categories.',
+          PASS: 'UI still coherent in 1 of 3. Pass with note.',
+          REVISE: 'UI still coherent in 2 of 3. Anchor is too generic. Revise the anchor to add product-specific constraints until it fails in at least 2 of 3.',
+          DISCARD: 'UI still coherent in 3 of 3. Anchor is category-agnostic. Discard immediately.',
+        },
+        requireTestCategoriesRecordedInDossier: true,
+        auditableByHumanReviewer: true,
+        renameTestRequiredFields: [
+          'testCategories',
+          'results',
+          'verdict',
+        ],
+      },
+      categoryCodeOverlapRule: 'List any Section 3 category codes this candidate accidentally inherits, with reasoning.',
+      forbiddenSelectedVerdicts: ['DISCARD'],
+      requiredSelectedVerdicts: ['STRONG PASS', 'PASS'],
+      candidates: [],
+    },
     finalAnchorContract: {
       requiredFields: [
         'name',

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

@@ -7,6 +7,12 @@
 
 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') {
@@ -166,6 +172,8 @@ export function validateConceptualAnchor(designIntentContract, 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".');
   }
@@ -204,6 +212,9 @@ export function validateConceptualAnchor(designIntentContract, validationErrors)
 
   validateVisualRiskBudgetAndLiteralPolicy(conceptualAnchor, validationErrors);
   validateFinalAnchorContract(conceptualAnchor, validationErrors);
+  validateCategoryCodes(conceptualAnchor, validationErrors, { isSeedStatus });
+  validateMorphologicalExploration(conceptualAnchor, validationErrors, { isSeedStatus });
+  validateAnchorCandidates(conceptualAnchor, validationErrors, { isSeedStatus });
   return validationErrors;
 }
 
@@ -220,3 +231,226 @@ export function validateMathSystems(designIntentContract, validationErrors) {
   }
   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/completeness.mjs

@@ -7,6 +7,15 @@
 
 import { hasNonEmptyString } from './helpers.mjs';
 
+const SEED_STATUSES = new Set([
+  'seed-needs-design-synthesis',
+  'seed-generated-during-init',
+  'seed-generated-during-upgrade',
+]);
+const REQUIRED_TOKEN_CATEGORIES = ['typography', 'palette', 'motion', 'spacing'];
+const ACTIVE_CLASSIFICATION_VALUES = new Set(['anchor-derived', 'continuity-retained', 'newly-introduced']);
+const SEED_CLASSIFICATION_VALUES = new Set(['anchor-derived', 'continuity-retained', 'newly-introduced', 'pending-research']);
+
 export function validateDesignContractCompleteness(designIntentContract) {
   const validationIssues = [];
   const conceptualAnchor = designIntentContract?.conceptualAnchor;
@@ -47,6 +56,35 @@ export function validateDesignContractCompleteness(designIntentContract) {
     ) {
       validationIssues.push('designIntent.derivedTokenLogic.validationRule must require traceability to anchorReference.');
     }
+
+    const tokenContinuityClassification = derivedTokenLogic.tokenContinuityClassification;
+    const isSeedStatus = SEED_STATUSES.has(designIntentContract?.status);
+    const allowedClassificationValues = isSeedStatus ? SEED_CLASSIFICATION_VALUES : ACTIVE_CLASSIFICATION_VALUES;
+    if (!tokenContinuityClassification || typeof tokenContinuityClassification !== 'object') {
+      validationIssues.push('designIntent.derivedTokenLogic.tokenContinuityClassification must exist. Each token category (typography, palette, motion, spacing) must declare anchor-derived, continuity-retained, or newly-introduced (pending-research is allowed only on seed contracts).');
+    } else {
+      if (
+        !Array.isArray(tokenContinuityClassification.validValues)
+        || !tokenContinuityClassification.validValues.includes('anchor-derived')
+        || !tokenContinuityClassification.validValues.includes('continuity-retained')
+        || !tokenContinuityClassification.validValues.includes('newly-introduced')
+        || !tokenContinuityClassification.validValues.includes('pending-research')
+      ) {
+        validationIssues.push('designIntent.derivedTokenLogic.tokenContinuityClassification.validValues must include anchor-derived, continuity-retained, newly-introduced, and pending-research.');
+      }
+      if (!hasNonEmptyString(tokenContinuityClassification.rule)) {
+        validationIssues.push('designIntent.derivedTokenLogic.tokenContinuityClassification.rule must explain when each value applies.');
+      }
+      for (const tokenCategoryName of REQUIRED_TOKEN_CATEGORIES) {
+        const classifiedValue = tokenContinuityClassification[tokenCategoryName];
+        if (!allowedClassificationValues.has(classifiedValue)) {
+          const allowedLabel = isSeedStatus
+            ? 'anchor-derived, continuity-retained, newly-introduced, or pending-research'
+            : 'anchor-derived, continuity-retained, or newly-introduced';
+          validationIssues.push(`designIntent.derivedTokenLogic.tokenContinuityClassification.${tokenCategoryName} must be one of: ${allowedLabel}. Got: "${classifiedValue}".`);
+        }
+      }
+    }
   }
 
   if (!['verified', 'pending-verification', 'no-external-library-needed'].includes(designIntentContract?.libraryResearchStatus)) {

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', 'previousTypographyChoices'];
+
+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.mjs

@@ -18,6 +18,7 @@ import {
   validateConceptualAnchor,
   validateMathSystems,
 } from './validation/anchor-validators.mjs';
+import { validateResearchDossier } from './validation/research-dossier-validators.mjs';
 import {
   validateAiSafeUiAudit,
   validateProductionContentPolicy,
@@ -54,6 +55,7 @@ export function validateDesignIntentContract(designIntentContract) {
   validateDesignFlexibilityPolicy(designIntentContract, validationErrors);
   validateConceptualAnchor(designIntentContract, validationErrors);
   validateMathSystems(designIntentContract, validationErrors);
+  validateResearchDossier(designIntentContract, validationErrors);
   validateAiSafeUiAudit(designIntentContract, validationErrors);
   validateProductionContentPolicy(designIntentContract, validationErrors);
   validateTokenSystem(designIntentContract, validationErrors);

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

@@ -22,6 +22,7 @@ import {
 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,
@@ -124,6 +125,9 @@ function buildDesignIntentContractObject({
       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: buildConceptualAnchorSection(),
+    researchDossier: {
+      metadata: buildResearchDossierMetadata(),
+    },
     derivedTokenLogic: {
       anchorReference: 'agent-defined-anchor-reference',
       colorDerivationSource: 'Explain semantic color roles from anchorReference; reject generic palettes without anchor evidence.',
@@ -135,6 +139,14 @@ function buildDesignIntentContractObject({
       typeScaleMethod: 'Prefer fluid clamp() type scales when supported; name ratio, role contrast, balance/wrap behavior, and numeric typography needs.',
       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.',
+      tokenContinuityClassification: {
+        typography: 'pending-research',
+        palette: 'pending-research',
+        motion: 'pending-research',
+        spacing: 'pending-research',
+        validValues: ['anchor-derived', 'continuity-retained', 'newly-introduced', 'pending-research'],
+        rule: 'For each token category, classify whether the choice is anchor-derived (causally tied to anchorReference real-world reality), continuity-retained (kept from a previous design iteration without re-derivation), or newly-introduced (fresh choice not tied to anchor). Continuity-retained is acceptable; pretending continuity is derivation is not.',
+      },
     },
     motionPaletteDecision: buildMotionPaletteDecisionSection(),
     aiSafeUiAudit: buildAiSafeUiAuditSection({ projectName }),
@@ -274,6 +286,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: [

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -190,6 +190,7 @@ export function buildDesignBootstrapPrompt({
     '29. repoEvidence when onboarding or detector evidence exists',
     '',
     '## Mechanical Gates',
+    '0. Read `.agent-context/prompts/research-design.md` first. Sections 3 (Category Code Identification), 4 (Morphological Exploration), and 5 (Anchor Candidates) are gates: each must produce an auditable artifact before UI implementation.',
     '1. Do not copy external style guides.',
     '2. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
     '3. Do not choose final style, library, palette, typography, motion, or layout from this offline scaffold.',
@@ -238,6 +239,13 @@ export function buildDesignBootstrapPrompt({
     '40. Translate conceptual anchors non-literally first. Do not turn anchor artifacts into required chrome, decorative props, wallpaper, or theme objects unless they serve a named product function.',
     '41. Use external websites and benchmark examples as candidate evidence for constraints, mechanics, and quality bars only; do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
     '',
+    '## Research-Design Brief Gates (research-design.md)',
+    '42. Section 3 — Category Code Identification: list at least three category codes per product surface in `conceptualAnchor.categoryCodes.candidateEntries`. Each entry must record `description`, `specificityEvidence`, `categoryDefaultReason`, and `rejectionNote`. The specificity floor is: a reader unfamiliar with the project must be able to visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name. Reject placeholder phrases like "clean typography", "modern color palette", or "smooth animations". Anti-leakage rule: listing a cliche identifies a trap, not a target; the example cliches in the brief are not aesthetic candidates for any project. If the project pattern-matches a common AI-safe default (dev-tool dark slate, AI-startup purple-pink gradient, health-app mint, SaaS admin three-card KPI, marketing-site three-tile hero), name that cliche in `candidateEntries` with an explicit rejection note.',
+    '43. Section 4 — Morphological Exploration: build a 5x5 or 6x5 matrix in `conceptualAnchor.morphologicalExploration`. Choose 5 or 6 dimensions and 5 values per dimension. Do not seed the matrix with the Section 3 category codes as values. Highlight the selected combination, and ALSO highlight at least one uncomfortable combination that feels instinctively wrong but can be argued with product logic. The uncomfortable combination must record `combinationLabel`, `discomfortReason`, and `productLogicJustification`. If you cannot produce an uncomfortable-but-arguable combination, the dimensions are too narrow; widen at least one and regenerate.',
+    '44. Section 5 — Anchor Candidates: produce exactly five entries in `conceptualAnchor.anchorCandidates.candidates`. Each candidate must record `anchorReference`, `conceptualFamily`, `jobFit`, `hierarchyImplication`, `densityImplication`, `typeImplication`, `stateLanguage`, `motionImplication`, `whatItRulesOut`, `renameTest`, and `categoryCodeOverlap`.',
+    '45. Strengthened rename test: rename the product to three genuinely different categories that are remote from each other and from the actual product. Pick fresh test categories per anchor; do not reuse the same triple across every anchor. Record the three test categories explicitly in the dossier so a human reviewer can audit them. Score the result: 0/3 coherent equals STRONG PASS, 1/3 equals PASS, 2/3 equals REVISE, 3/3 equals DISCARD. Never select an anchor with verdict DISCARD; revise REVISE candidates until they fail in at least 2 of 3 categories.',
+    '46. Make `conceptualAnchor.anchorReference` and `derivedTokenLogic.anchorReference` match the selected anchor exactly. The selected anchor must have verdict STRONG PASS or PASS.',
+    '',
     '## Creative Ambition Floor',
     'Before implementation, the design contract must name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that would not appear in a generic AI template.',
     'The ambition floor is not a fixed aesthetic. Quiet, dense, utilitarian, or text-heavy interfaces are allowed when the product requires them, but they still need a project-specific visual decision and a real reason for omitting richer motion, 3D, canvas, WebGL, scroll choreography, or animation libraries.',
@@ -290,6 +298,7 @@ export function buildDesignBootstrapPrompt({
     '13. Preserve externalResearchIntake so user-provided research becomes reviewed evidence without turning into an offline style or dependency preset.',
     '14. Preserve conceptualAnchor so prompt-only UI work has one cohesive non-template concept instead of a mixed collection of bold but unrelated visual decisions.',
     '15. Record conceptualAnchor.agentResearchMode, specificReferencePoint, signatureMotion, typographicDecision, visualRiskBudget, motionRiskBudget, and cohesionChecks so the final UI cannot quietly fall back to a timid dashboard/admin mental model.',
+    '15a. Record conceptualAnchor.categoryCodes.candidateEntries (Section 3 of research-design.md), conceptualAnchor.morphologicalExploration with selectedCombination and uncomfortableCombination (Section 4), and conceptualAnchor.anchorCandidates.candidates with full renameTest results (Section 5) before UI implementation.',
     '16. Preserve derivedTokenLogic, libraryResearchStatus, and libraryDecisions so token choices and dependency uncertainty stay visible before implementation.',
     '16a. Preserve designFlexibilityPolicy so the machine contract guides consistency without freezing literal anchor artifacts, exact token primitives, or component-kit visual language.',
     '17. Preserve productionContentPolicy so UI output is ship-ready and not a testing-looking scaffold.',