@ryuenn3123/agentic-senior-core 4.0.1 → 4.0.3

package/.agent-context/prompts/bootstrap-design.md

@@ -20,7 +20,8 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 5. Encode `repoEvidence.designEvidenceSummary` when onboarding or detector evidence exists.
 6. Keep both design docs synchronized after implementation.
 7. Complete the Section 3-5 gates from `research-design.md` before UI implementation: `conceptualAnchor.categoryCodes.candidateEntries`, `conceptualAnchor.morphologicalExploration` (selected and uncomfortable combinations), and `conceptualAnchor.anchorCandidates.candidates` (exactly five, each with the strengthened rename test recorded).
-8. After agent and user select an anchor, set `researchDossier.metadata.researchVerifiedAt` to today's ISO date and flip `status` from any seed value to `active`. This closes the freshness window for additive UI tasks within `freshnessWindowDays`.
+8. Set `derivedTokenLogic.tokenContinuityClassification` for each of typography, palette, motion, and spacing. Use `anchor-derived` only when the token choice is causally tied to the anchor's real-world reality. Use `continuity-retained` when the token is kept from a previous design iteration without re-derivation. Use `newly-introduced` when the token is fresh but not anchor-derived. If any token category is `continuity-retained`, the typography, palette, or motion entry in `researchDossier.metadata.antiRepeatLedger` stays as historical record, and the classification declares the retention is intentional with explicit rationale recorded in the matching `derivationSource` field.
+9. After agent and user select an anchor, set `researchDossier.metadata.researchVerifiedAt` to today's ISO date and flip `status` from any seed value to `active`. This closes the freshness window for additive UI tasks within `freshnessWindowDays`.
 ## Creative Commitment Gate
 Before broad compliance review or UI implementation, record an agent-chosen visual direction in both design docs:
 - one concrete real-world anchor reference

package/.agent-context/prompts/research-design.md

@@ -90,6 +90,23 @@ Self-test: read each category code aloud to someone unfamiliar with the project.
 
 Output: at least three category codes per product surface in `categoryCodes`. Each entry must pass the specificity self-test, must include the one-sentence reason that pattern is the default for the category, and must include an explicit one-sentence rejection note ("I will not ship this; here is the trap it sets") so the cliche cannot quietly become the target.
 
+### Dimensional split (mandatory)
+
+Category codes must be broken down by dimension. Do not collapse multiple dimensions into a single category-level cliche. Each cluster lists the patterns that the product category will default to without intervention.
+
+- `typographyClusters`: font family combinations that are the category default. Be explicit about font families. Name the actual trio or pair that this product's category currently defaults to, derived from live portfolio observation for THIS task. Do not anchor on examples from other categories or other timeframes.
+- `paletteClusters`: palette signatures that are the category default.
+- `layoutClusters`: layout patterns that are the category default.
+- `motionClusters`: motion signatures that are the category default.
+- `imageryClusters`: image style or visual treatment that is the category default.
+
+Self-check before proceeding to Section 4: do the typography choices the agent is about to commit to in `derivedTokenLogic` (or downstream token sections) overlap with any item in `typographyClusters`? If yes, the agent must either:
+
+1. Flag the typography as a continuity choice with an explicit rationale, set `derivedTokenLogic.tokenContinuityClassification.typography` to `continuity-retained`, and record the reason that font family swap is deferred. The previous typography ledger entry stays as historical record; the classification declares the retention is intentional. OR
+2. Revise the typography pick to escape the autopilot cluster and set `tokenContinuityClassification.typography` to `anchor-derived` only when the new choice is causally tied to the anchor's real-world reality.
+
+This self-check applies to every dimension, not only typography. Do not let an output token match a category-code item from the agent's own list without explicit (1) or (2) treatment per dimension. Pretending continuity is derivation is the failure mode this gate exists to prevent.
+
 ## Section 4 — Morphological Exploration
 
 A morphological matrix forces the design space to be explored beyond the first idea.

package/README.md

@@ -63,6 +63,8 @@ The intended behavior is agent-led, not offline-template-led:
 - Modern UI claims: research current-year libraries and patterns when relevant; 2026 work should use 2026 evidence, and future years should update automatically through agent research.
 - Anti-generic rule: avoid safe dashboard shells, admin panels, card grids, scale-only mobile layouts, and static no-motion interfaces unless the product context explicitly justifies them.
 
+UI design work runs a research dossier prompt (`.agent-context/prompts/research-design.md`) before the bootstrap prompt. The dossier captures product reading, reference intake, category cliches, a morphological matrix, and five anchor candidates with a strengthened rename test. The contract carries a 90-day `researchVerifiedAt` freshness gate and an anti-repeat ledger seeded from prior anchor, palette, motion, and typography choices on existing projects, so additive UI work within the freshness window skips the research stage while redesigns and stale dossiers re-run it.
+
 ---
 
 ## MCP Quick Setup (VS Code)

package/bin/agentic-senior-core.js

@@ -15,6 +15,7 @@ import { runMcpServerCommand } from '../lib/cli/commands/mcp.mjs';
 import { runOptimizeCommand, parseOptimizeArguments } from '../lib/cli/commands/optimize.mjs';
 import { runInitCommand, parseInitArguments } from '../lib/cli/commands/init.mjs';
 import { runUpgradeCommand, parseUpgradeArguments } from '../lib/cli/commands/upgrade.mjs';
+import { runDesignAntiRepeatAuditCommand } from '../lib/cli/commands/audit-design-anti-repeat.mjs';
 
 async function main() {
   const commandArgument = process.argv[2];
@@ -63,6 +64,11 @@ async function main() {
     return;
   }
 
+  if (commandArgument === 'audit:design-anti-repeat') {
+    const auditExitCode = await runDesignAntiRepeatAuditCommand(commandArguments);
+    exit(auditExitCode);
+  }
+
   console.error(`Unknown command: ${commandArgument}`);
   printUsage();
   exit(1);

package/lib/cli/audits/typography-palette-anti-repeat/color-utils.mjs

@@ -0,0 +1,156 @@
+// @ts-check
+
+/**
+ * Color parsing and distance utilities for the typography/palette
+ * anti-repeat audit. OKLCH math is contained here so the main audit module
+ * stays focused on file scanning and ledger cross-check.
+ */
+
+export const HEX_COLOR_PATTERN = /#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+export const OKLCH_PATTERN = /oklch\(\s*([^)]+)\s*\)/gi;
+
+export function expandShortHexColor(rawHexColor) {
+  if (rawHexColor.length !== 4) {
+    return rawHexColor;
+  }
+  const expandedChars = [];
+  for (let charIndex = 1; charIndex < rawHexColor.length; charIndex += 1) {
+    expandedChars.push(rawHexColor[charIndex], rawHexColor[charIndex]);
+  }
+  return `#${expandedChars.join('')}`.toLowerCase();
+}
+
+export function normalizeHexColor(rawHexColor) {
+  if (typeof rawHexColor !== 'string' || rawHexColor.length === 0) {
+    return null;
+  }
+  const trimmedHex = rawHexColor.trim().toLowerCase();
+  if (!trimmedHex.startsWith('#')) {
+    return null;
+  }
+  if (trimmedHex.length === 4) {
+    return expandShortHexColor(trimmedHex);
+  }
+  if (trimmedHex.length === 7 || trimmedHex.length === 9) {
+    return trimmedHex.slice(0, 7);
+  }
+  return null;
+}
+
+function parseOklchNumber(rawNumber, percentScale) {
+  const numberString = String(rawNumber || '').trim();
+  if (numberString.endsWith('%')) {
+    const percentValue = parseFloat(numberString.slice(0, -1));
+    if (!Number.isFinite(percentValue)) {
+      return Number.NaN;
+    }
+    return (percentValue / 100) * percentScale;
+  }
+  return parseFloat(numberString);
+}
+
+export function parseOklchTriple(oklchExpression) {
+  const componentTokens = String(oklchExpression || '')
+    .replace(/\//g, ' ')
+    .split(/[\s,]+/)
+    .filter((componentToken) => componentToken.length > 0);
+  if (componentTokens.length < 3) {
+    return null;
+  }
+  const lightness = parseOklchNumber(componentTokens[0], 1);
+  const chroma = parseFloat(componentTokens[1]);
+  const hueDegrees = parseOklchNumber(componentTokens[2], 360);
+  if (!Number.isFinite(lightness) || !Number.isFinite(chroma) || !Number.isFinite(hueDegrees)) {
+    return null;
+  }
+  return { lightness, chroma, hueDegrees };
+}
+
+/**
+ * L*C*H-style perceptual distance proxy. OKLCH is perceptually uniform,
+ * so a Cartesian-like delta over (L, C, C * Δhue_radians) tracks visible
+ * difference well enough for an anti-repeat heuristic.
+ */
+export function oklchPerceptualDistance(leftColor, rightColor) {
+  const lightnessDelta = leftColor.lightness - rightColor.lightness;
+  const chromaDelta = leftColor.chroma - rightColor.chroma;
+  const hueDelta = ((leftColor.hueDegrees - rightColor.hueDegrees + 540) % 360) - 180;
+  const hueArcRadians = (hueDelta * Math.PI) / 180;
+  const hueChromaDelta = leftColor.chroma * hueArcRadians;
+  return Math.sqrt(
+    lightnessDelta * lightnessDelta
+    + chromaDelta * chromaDelta
+    + hueChromaDelta * hueChromaDelta,
+  );
+}
+
+export function extractColorOccurrencesFromText(sourceText) {
+  /** @type {{ kind: 'hex' | 'oklch', raw: string, normalized: string | null, oklch: { lightness: number, chroma: number, hueDegrees: number } | null, index: number }[]} */
+  const colorOccurrences = [];
+
+  HEX_COLOR_PATTERN.lastIndex = 0;
+  let hexMatch;
+  // eslint-disable-next-line no-cond-assign
+  while ((hexMatch = HEX_COLOR_PATTERN.exec(sourceText)) !== null) {
+    colorOccurrences.push({
+      kind: 'hex',
+      raw: hexMatch[0],
+      normalized: normalizeHexColor(hexMatch[0]),
+      oklch: null,
+      index: hexMatch.index,
+    });
+  }
+
+  OKLCH_PATTERN.lastIndex = 0;
+  let oklchMatch;
+  // eslint-disable-next-line no-cond-assign
+  while ((oklchMatch = OKLCH_PATTERN.exec(sourceText)) !== null) {
+    colorOccurrences.push({
+      kind: 'oklch',
+      raw: oklchMatch[0],
+      normalized: oklchMatch[0].toLowerCase(),
+      oklch: parseOklchTriple(oklchMatch[1]),
+      index: oklchMatch.index,
+    });
+  }
+
+  return colorOccurrences;
+}
+
+export function extractLedgerColors(antiRepeatLedger) {
+  const previousPalettes = Array.isArray(antiRepeatLedger?.previousPalettes)
+    ? antiRepeatLedger.previousPalettes
+    : [];
+
+  /** @type {{ kind: 'hex' | 'oklch', normalized: string | null, oklch: { lightness: number, chroma: number, hueDegrees: number } | null, sourceEntry: any }[]} */
+  const ledgerColors = [];
+  for (const ledgerEntry of previousPalettes) {
+    const summaryString = String(ledgerEntry?.summary || '');
+    if (!summaryString) {
+      continue;
+    }
+    HEX_COLOR_PATTERN.lastIndex = 0;
+    let hexMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((hexMatch = HEX_COLOR_PATTERN.exec(summaryString)) !== null) {
+      ledgerColors.push({
+        kind: 'hex',
+        normalized: normalizeHexColor(hexMatch[0]),
+        oklch: null,
+        sourceEntry: ledgerEntry,
+      });
+    }
+    OKLCH_PATTERN.lastIndex = 0;
+    let oklchMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((oklchMatch = OKLCH_PATTERN.exec(summaryString)) !== null) {
+      ledgerColors.push({
+        kind: 'oklch',
+        normalized: oklchMatch[0].toLowerCase(),
+        oklch: parseOklchTriple(oklchMatch[1]),
+        sourceEntry: ledgerEntry,
+      });
+    }
+  }
+  return ledgerColors;
+}

package/lib/cli/audits/typography-palette-anti-repeat/file-scanner.mjs

@@ -0,0 +1,103 @@
+// @ts-check
+
+/**
+ * Filesystem scanning for the typography/palette anti-repeat audit. Walks
+ * the repository tree, skips noisy directories (node_modules, build outputs,
+ * etc.), and yields scannable CSS-like and token-config file paths.
+ */
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+
+export const DEFAULT_CSS_FILE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+export const TOKEN_CONFIG_FILE_NAMES = new Set([
+  'tailwind.config.js',
+  'tailwind.config.cjs',
+  'tailwind.config.mjs',
+  'tailwind.config.ts',
+  'theme.config.js',
+  'theme.config.ts',
+  'design-tokens.js',
+  'design-tokens.ts',
+]);
+export const SCAN_SKIP_DIRECTORY_NAMES = new Set([
+  'node_modules',
+  '.git',
+  '.agentic-backup',
+  '.benchmarks',
+  'dist',
+  'build',
+  '.next',
+  'out',
+  'coverage',
+  '.cache',
+]);
+
+function isInsideSkippedDirectory(absolutePath, repositoryRootPath) {
+  const relativePath = relative(repositoryRootPath, absolutePath);
+  if (!relativePath || relativePath.startsWith('..')) {
+    return true;
+  }
+  const pathSegments = relativePath.split(sep);
+  return pathSegments.some((segmentName) => SCAN_SKIP_DIRECTORY_NAMES.has(segmentName));
+}
+
+function* walkDirectoryEntries(currentDirectoryPath, repositoryRootPath) {
+  const directoryEntries = readdirSync(currentDirectoryPath, { withFileTypes: true });
+  for (const directoryEntry of directoryEntries) {
+    const childPath = join(currentDirectoryPath, directoryEntry.name);
+    if (directoryEntry.isDirectory()) {
+      if (SCAN_SKIP_DIRECTORY_NAMES.has(directoryEntry.name)) {
+        continue;
+      }
+      if (isInsideSkippedDirectory(childPath, repositoryRootPath)) {
+        continue;
+      }
+      yield* walkDirectoryEntries(childPath, repositoryRootPath);
+      continue;
+    }
+    if (directoryEntry.isFile()) {
+      yield childPath;
+    }
+  }
+}
+
+export function isScannableFile(absoluteFilePath) {
+  const fileExtension = extname(absoluteFilePath).toLowerCase();
+  if (DEFAULT_CSS_FILE_EXTENSIONS.has(fileExtension)) {
+    return true;
+  }
+  const baseName = absoluteFilePath.split(/[\\/]/).pop();
+  return TOKEN_CONFIG_FILE_NAMES.has(baseName);
+}
+
+export function collectScannableFilePaths(repositoryRootPath, scanRoots) {
+  const collectedFilePaths = [];
+  for (const scanRoot of scanRoots) {
+    const absoluteScanRoot = join(repositoryRootPath, scanRoot);
+    if (!existsSync(absoluteScanRoot)) {
+      continue;
+    }
+    const scanRootStat = statSync(absoluteScanRoot);
+    if (!scanRootStat.isDirectory()) {
+      continue;
+    }
+    for (const candidateFilePath of walkDirectoryEntries(absoluteScanRoot, repositoryRootPath)) {
+      if (!isScannableFile(candidateFilePath)) {
+        continue;
+      }
+      collectedFilePaths.push(candidateFilePath);
+    }
+  }
+  return collectedFilePaths.sort();
+}
+
+export function lineNumberFromIndex(sourceText, charIndex) {
+  let lineNumber = 1;
+  for (let scanIndex = 0; scanIndex < charIndex && scanIndex < sourceText.length; scanIndex += 1) {
+    if (sourceText[scanIndex] === '\n') {
+      lineNumber += 1;
+    }
+  }
+  return lineNumber;
+}

package/lib/cli/audits/typography-palette-anti-repeat/typography-utils.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+/**
+ * Font-family parsing for the typography/palette anti-repeat audit. CSS
+ * `font-family:` declarations and `@font-face` blocks are the inputs;
+ * normalized lowercase family tokens are the outputs.
+ */
+
+export const FONT_FAMILY_DECLARATION_PATTERN = /font-family\s*:\s*([^;}]+)[;}]/gi;
+export const FONT_FACE_FAMILY_PATTERN = /@font-face\s*\{[^}]*font-family\s*:\s*([^;]+);/gi;
+
+export function normalizeFontFamilyToken(rawFamilyToken) {
+  return String(rawFamilyToken || '')
+    .replace(/^["']|["']$/g, '')
+    .trim()
+    .toLowerCase();
+}
+
+export function splitFontFamilyDeclaration(declarationValue) {
+  return String(declarationValue || '')
+    .split(',')
+    .map((familyEntry) => normalizeFontFamilyToken(familyEntry))
+    .filter((familyEntry) => familyEntry.length > 0 && !familyEntry.startsWith('var('));
+}
+
+export function extractFontFamiliesFromText(sourceText) {
+  /** @type {{ family: string, index: number }[]} */
+  const familyOccurrences = [];
+
+  for (const matchPattern of [FONT_FAMILY_DECLARATION_PATTERN, FONT_FACE_FAMILY_PATTERN]) {
+    matchPattern.lastIndex = 0;
+    let regexMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((regexMatch = matchPattern.exec(sourceText)) !== null) {
+      const declarationValue = regexMatch[1];
+      const declarationStartIndex = regexMatch.index;
+      for (const familyEntry of splitFontFamilyDeclaration(declarationValue)) {
+        familyOccurrences.push({ family: familyEntry, index: declarationStartIndex });
+      }
+    }
+  }
+
+  return familyOccurrences;
+}
+
+export function extractLedgerTypographyFamilies(antiRepeatLedger) {
+  const previousTypographyChoices = Array.isArray(antiRepeatLedger?.previousTypographyChoices)
+    ? antiRepeatLedger.previousTypographyChoices
+    : [];
+
+  const ledgerFamilies = new Map();
+  for (const ledgerEntry of previousTypographyChoices) {
+    const summaryString = String(ledgerEntry?.summary || '');
+    if (!summaryString) {
+      continue;
+    }
+    // Summaries are emitted as "role: value; role: value". Each value is a
+    // font family that the previous design shipped.
+    for (const summaryPart of summaryString.split(';')) {
+      const colonSplitIndex = summaryPart.indexOf(':');
+      const familyValue = colonSplitIndex >= 0 ? summaryPart.slice(colonSplitIndex + 1) : summaryPart;
+      const normalizedFamilyValue = normalizeFontFamilyToken(familyValue);
+      if (normalizedFamilyValue.length === 0) {
+        continue;
+      }
+      ledgerFamilies.set(normalizedFamilyValue, ledgerEntry);
+    }
+  }
+  return ledgerFamilies;
+}

package/lib/cli/audits/typography-palette-anti-repeat-audit.mjs

@@ -0,0 +1,255 @@
+// @ts-check
+
+/**
+ * Typography and palette anti-repeat audit.
+ *
+ * Scans CSS-like files for font-family declarations and color values, then
+ * cross-checks them against
+ * `docs/design-intent.json`'s
+ * `researchDossier.metadata.antiRepeatLedger.previousTypographyChoices` and
+ * `previousPalettes` so a redesign cannot leak the previous direction's
+ * exact font trio or perceptually-identical palette colors through CSS
+ * implementation files alone.
+ *
+ * Severity model:
+ *   - Typography matches are EXACT family-name matches and are always
+ *     blocking (kind: typography.previously-shipped-family,
+ *     diagnosticCode: BOUNDARY_TYPOGRAPHY_LEDGER_VIOLATION).
+ *   - Palette matches are HEURISTIC. OKLCH-to-OKLCH distance is perceptually
+ *     uniform (deltaE < threshold => match). Hex-to-hex matches are exact
+ *     normalized equality. Cross-type matches (hex declared in CSS vs OKLCH
+ *     in the ledger, or vice versa) are NOT performed; reporting cross-type
+ *     would require a color-space conversion that is its own correctness
+ *     surface (tracked in docs/deep-analysis-and-roadmap-backlog.md).
+ *   - Palette findings BLOCK by default with kind:
+ *     palette.previously-shipped-color and diagnosticCode:
+ *     BOUNDARY_PALETTE_LEDGER_VIOLATION. Pass
+ *     `treatPaletteAsAdvisory: true` (or `--palette-advisory` on the CLI)
+ *     to opt a project into advisory-only palette reporting; severity drops
+ *     to "advisory" and the diagnostic code becomes
+ *     BOUNDARY_PALETTE_LEDGER_ADVISORY. Use the advisory mode only when a
+ *     project knowingly accepts the false-positive risk of OKLCH distance
+ *     matching at its chosen threshold.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import {
+  collectScannableFilePaths,
+  lineNumberFromIndex,
+} from './typography-palette-anti-repeat/file-scanner.mjs';
+import {
+  extractFontFamiliesFromText,
+  extractLedgerTypographyFamilies,
+} from './typography-palette-anti-repeat/typography-utils.mjs';
+import {
+  extractColorOccurrencesFromText,
+  extractLedgerColors,
+  oklchPerceptualDistance,
+} from './typography-palette-anti-repeat/color-utils.mjs';
+
+const DEFAULT_OKLCH_DISTANCE_THRESHOLD = 0.04;
+
+function findTypographyViolationsForFile({ relativeFilePath, sourceText, ledgerFamilies }) {
+  const violations = [];
+  const fontFamilyOccurrences = extractFontFamiliesFromText(sourceText);
+  for (const familyOccurrence of fontFamilyOccurrences) {
+    const ledgerEntry = ledgerFamilies.get(familyOccurrence.family);
+    if (!ledgerEntry) {
+      continue;
+    }
+    violations.push({
+      file: relativeFilePath,
+      line: lineNumberFromIndex(sourceText, familyOccurrence.index),
+      kind: 'typography.previously-shipped-family',
+      severity: 'blocking',
+      diagnosticCode: 'BOUNDARY_TYPOGRAPHY_LEDGER_VIOLATION',
+      detail: `CSS declares font-family "${familyOccurrence.family}" which appears in researchDossier.metadata.antiRepeatLedger.previousTypographyChoices ("${ledgerEntry.summary}"). Either escape the previously-shipped trio, or set derivedTokenLogic.tokenContinuityClassification.typography to continuity-retained with explicit rationale.`,
+    });
+  }
+  return violations;
+}
+
+function buildHexAdvisory({ relativeFilePath, sourceText, colorOccurrence, ledgerColor, paletteSeverity, paletteDiagnosticCode }) {
+  return {
+    file: relativeFilePath,
+    line: lineNumberFromIndex(sourceText, colorOccurrence.index),
+    kind: 'palette.previously-shipped-color',
+    severity: paletteSeverity,
+    diagnosticCode: paletteDiagnosticCode,
+    detail: `CSS hex "${colorOccurrence.raw}" matches a hex color in researchDossier.metadata.antiRepeatLedger.previousPalettes ("${ledgerColor.sourceEntry.summary}"). Either escape the previously-shipped palette or set derivedTokenLogic.tokenContinuityClassification.palette to continuity-retained with explicit rationale.`,
+  };
+}
+
+function buildOklchAdvisory({ relativeFilePath, sourceText, colorOccurrence, ledgerColor, perceptualDistance, oklchDistanceThreshold, paletteSeverity, paletteDiagnosticCode }) {
+  return {
+    file: relativeFilePath,
+    line: lineNumberFromIndex(sourceText, colorOccurrence.index),
+    kind: 'palette.previously-shipped-color',
+    severity: paletteSeverity,
+    diagnosticCode: paletteDiagnosticCode,
+    detail: `CSS OKLCH "${colorOccurrence.raw}" is within ${perceptualDistance.toFixed(4)} of an OKLCH color in researchDossier.metadata.antiRepeatLedger.previousPalettes ("${ledgerColor.sourceEntry.summary}") (threshold ${oklchDistanceThreshold}). Heuristic match on perceptually-uniform OKLCH distance; either escape the previously-shipped palette, raise the threshold via --threshold, or set derivedTokenLogic.tokenContinuityClassification.palette to continuity-retained with explicit rationale.`,
+  };
+}
+
+function findPaletteFindingsForFile({ relativeFilePath, sourceText, ledgerColors, oklchDistanceThreshold, paletteSeverity, paletteDiagnosticCode }) {
+  const findings = [];
+  const colorOccurrences = extractColorOccurrencesFromText(sourceText);
+  for (const colorOccurrence of colorOccurrences) {
+    for (const ledgerColor of ledgerColors) {
+      if (colorOccurrence.kind === 'hex' && ledgerColor.kind === 'hex') {
+        if (
+          colorOccurrence.normalized
+          && ledgerColor.normalized
+          && colorOccurrence.normalized === ledgerColor.normalized
+        ) {
+          findings.push(buildHexAdvisory({
+            relativeFilePath, sourceText, colorOccurrence, ledgerColor,
+            paletteSeverity, paletteDiagnosticCode,
+          }));
+        }
+        continue;
+      }
+      if (colorOccurrence.kind === 'oklch' && ledgerColor.kind === 'oklch' && colorOccurrence.oklch && ledgerColor.oklch) {
+        const perceptualDistance = oklchPerceptualDistance(colorOccurrence.oklch, ledgerColor.oklch);
+        if (perceptualDistance <= oklchDistanceThreshold) {
+          findings.push(buildOklchAdvisory({
+            relativeFilePath, sourceText, colorOccurrence, ledgerColor, perceptualDistance, oklchDistanceThreshold,
+            paletteSeverity, paletteDiagnosticCode,
+          }));
+        }
+      }
+      // Cross-type (hex declared vs OKLCH ledger or vice versa) is intentionally
+      // skipped here; reporting cross-type would require a color-space conversion
+      // pass that is its own correctness surface. Tracked in
+      // docs/deep-analysis-and-roadmap-backlog.md.
+    }
+  }
+  return findings;
+}
+
+function loadDesignIntentContract(repositoryRootPath, designIntentRelativePath) {
+  const designIntentAbsolutePath = join(repositoryRootPath, designIntentRelativePath);
+  if (!existsSync(designIntentAbsolutePath)) {
+    return { contract: null, reason: 'design-intent-file-absent' };
+  }
+  let contract;
+  try {
+    contract = JSON.parse(readFileSync(designIntentAbsolutePath, 'utf8'));
+  } catch (parseError) {
+    const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
+    return { contract: null, reason: `design-intent-file-not-valid-json: ${errorMessage}` };
+  }
+  return { contract, reason: 'ok' };
+}
+
+function buildSkippedReport(reportShell, reason) {
+  return {
+    ...reportShell,
+    passed: true,
+    skipped: true,
+    reason,
+    filesScanned: 0,
+    typographyViolationCount: 0,
+    paletteFindingCount: 0,
+    typographyViolations: [],
+    paletteFindings: [],
+  };
+}
+
+/**
+ * Runs the typography and palette anti-repeat audit.
+ *
+ * @param {object} [auditOptions]
+ * @param {string} [auditOptions.repositoryRootPath]
+ * @param {string[]} [auditOptions.scanRoots]
+ * @param {string} [auditOptions.designIntentRelativePath]
+ * @param {number} [auditOptions.oklchDistanceThreshold]
+ * @param {boolean} [auditOptions.treatPaletteAsAdvisory]
+ */
+export function runTypographyPaletteAntiRepeatAudit(auditOptions = {}) {
+  const repositoryRootPath = auditOptions.repositoryRootPath || process.cwd();
+  const scanRoots = Array.isArray(auditOptions.scanRoots) && auditOptions.scanRoots.length > 0
+    ? auditOptions.scanRoots
+    : ['.'];
+  const designIntentRelativePath = auditOptions.designIntentRelativePath || 'docs/design-intent.json';
+  const oklchDistanceThreshold = typeof auditOptions.oklchDistanceThreshold === 'number'
+    ? auditOptions.oklchDistanceThreshold
+    : DEFAULT_OKLCH_DISTANCE_THRESHOLD;
+  const treatPaletteAsAdvisory = auditOptions.treatPaletteAsAdvisory === true;
+  const paletteSeverity = treatPaletteAsAdvisory ? 'advisory' : 'blocking';
+  const paletteDiagnosticCode = treatPaletteAsAdvisory
+    ? 'BOUNDARY_PALETTE_LEDGER_ADVISORY'
+    : 'BOUNDARY_PALETTE_LEDGER_VIOLATION';
+
+  const reportShell = {
+    auditName: 'audit-typography-palette-anti-repeat',
+    reportVersion: '2.0.0',
+    generatedAt: new Date().toISOString(),
+    designIntentRelativePath,
+    paletteSeverity,
+    paletteDiagnosticCode,
+    oklchDistanceThreshold,
+    scope: {
+      typographyMatching: 'exact-family-name-after-normalization',
+      paletteHexMatching: 'exact-hex-after-7-digit-normalization',
+      paletteOklchMatching: 'l*c*h-distance-under-threshold',
+      paletteCrossTypeMatching: 'not-supported-color-conversion-out-of-scope',
+      paletteCrossTypeMatchingTrackedIn: 'docs/deep-analysis-and-roadmap-backlog.md',
+    },
+  };
+
+  const designIntentLoad = loadDesignIntentContract(repositoryRootPath, designIntentRelativePath);
+  if (!designIntentLoad.contract) {
+    return buildSkippedReport(reportShell, designIntentLoad.reason);
+  }
+
+  const antiRepeatLedger = designIntentLoad.contract?.researchDossier?.metadata?.antiRepeatLedger;
+  if (!antiRepeatLedger || typeof antiRepeatLedger !== 'object') {
+    return buildSkippedReport(reportShell, 'anti-repeat-ledger-absent');
+  }
+
+  const ledgerFamilies = extractLedgerTypographyFamilies(antiRepeatLedger);
+  const ledgerColors = extractLedgerColors(antiRepeatLedger);
+  const scannableFilePaths = collectScannableFilePaths(repositoryRootPath, scanRoots);
+
+  /** @type {any[]} */
+  const typographyViolations = [];
+  /** @type {any[]} */
+  const paletteFindings = [];
+
+  for (const absoluteFilePath of scannableFilePaths) {
+    const relativeFilePath = relative(repositoryRootPath, absoluteFilePath).replace(/\\/g, '/');
+    let sourceText;
+    try {
+      sourceText = readFileSync(absoluteFilePath, 'utf8');
+    } catch {
+      continue;
+    }
+    if (ledgerFamilies.size > 0) {
+      typographyViolations.push(...findTypographyViolationsForFile({
+        relativeFilePath, sourceText, ledgerFamilies,
+      }));
+    }
+    if (ledgerColors.length > 0) {
+      paletteFindings.push(...findPaletteFindingsForFile({
+        relativeFilePath, sourceText, ledgerColors, oklchDistanceThreshold,
+        paletteSeverity, paletteDiagnosticCode,
+      }));
+    }
+  }
+
+  const blockingViolationCount = typographyViolations.length + (treatPaletteAsAdvisory ? 0 : paletteFindings.length);
+
+  return {
+    ...reportShell,
+    passed: blockingViolationCount === 0,
+    skipped: false,
+    filesScanned: scannableFilePaths.length,
+    typographyViolationCount: typographyViolations.length,
+    paletteFindingCount: paletteFindings.length,
+    typographyViolations,
+    paletteFindings,
+  };
+}

package/lib/cli/commands/audit-design-anti-repeat.mjs

@@ -0,0 +1,198 @@
+// @ts-check
+
+/**
+ * `agentic-senior-core audit:design-anti-repeat`
+ *
+ * User-facing CLI subcommand that runs the typography/palette anti-repeat
+ * audit against a user project's working directory. The default scan root is
+ * `process.cwd()` so `npx @ryuenn3123/agentic-senior-core audit:design-anti-repeat`
+ * inside a user project scans that project (not the package install).
+ *
+ * Skip behavior is friendly: missing design-intent.json or missing ledger
+ * print actionable next steps and exit 0. Typography violations and palette
+ * findings (when palette is blocking, which is the default) exit 1.
+ */
+
+import { resolve } from 'node:path';
+
+import { runTypographyPaletteAntiRepeatAudit } from '../audits/typography-palette-anti-repeat-audit.mjs';
+
+const HELP_TEXT_LINES = [
+  'agentic-senior-core audit:design-anti-repeat',
+  '',
+  'Scan CSS, SCSS, SASS, LESS, and Tailwind/theme/design-token config files in',
+  'the current project for typography or palette values that match the',
+  'anti-repeat ledger in docs/design-intent.json. Catches redesigns that leak',
+  "the previous direction's font trio or palette through CSS implementation",
+  'even when the JSON design contract claims a fresh anchor.',
+  '',
+  'Usage:',
+  '  agentic-senior-core audit:design-anti-repeat',
+  '  agentic-senior-core audit:design-anti-repeat [target-directory]',
+  '  agentic-senior-core audit:design-anti-repeat --json',
+  '  agentic-senior-core audit:design-anti-repeat --palette-advisory',
+  '  agentic-senior-core audit:design-anti-repeat --threshold 0.05',
+  '',
+  'Defaults:',
+  '  Target directory:    current working directory',
+  '  Typography matches:  blocking (BOUNDARY_TYPOGRAPHY_LEDGER_VIOLATION)',
+  '  Palette matches:     blocking (BOUNDARY_PALETTE_LEDGER_VIOLATION)',
+  '  OKLCH distance:      0.04 in L*C*H space',
+  '',
+  'Options:',
+  '  --json               Print the full report as JSON only (no human summary).',
+  '  --palette-advisory   Opt out of blocking palette severity. Findings still',
+  '                       print but do not fail the run. Typography stays blocking.',
+  '  --threshold <num>    Override the OKLCH perceptual distance threshold.',
+  '                       Higher values are more permissive.',
+  '  --help               Show this help.',
+  '',
+  'Skip behavior (exit 0):',
+  '  - docs/design-intent.json absent. Run `npx @ryuenn3123/agentic-senior-core init`',
+  '    in a fresh project, or `... upgrade` in an existing project to seed the',
+  '    design contract.',
+  '  - docs/design-intent.json present but researchDossier metadata absent.',
+  "    Run `... upgrade` to migrate the contract, then run `.agent-context/prompts/research-design.md`",
+  '    so the dossier and anti-repeat ledger get populated before the next UI work.',
+  '',
+  'Exit codes:',
+  '  0 = no blocking violations (or audit skipped with a friendly note).',
+  '  1 = at least one BOUNDARY_TYPOGRAPHY_LEDGER_VIOLATION or, in default mode,',
+  '      BOUNDARY_PALETTE_LEDGER_VIOLATION.',
+];
+
+function buildHelpText() {
+  return HELP_TEXT_LINES.join('\n');
+}
+
+function readNumericFlag(commandLineArgs, flagName) {
+  const flagIndex = commandLineArgs.indexOf(flagName);
+  if (flagIndex === -1) {
+    return null;
+  }
+  const flagValue = commandLineArgs[flagIndex + 1];
+  if (typeof flagValue !== 'string' || flagValue.length === 0) {
+    return null;
+  }
+  const numericValue = Number(flagValue);
+  return Number.isFinite(numericValue) ? numericValue : null;
+}
+
+const VALUE_FLAGS = new Set(['--threshold']);
+
+function extractTargetDirectoryArgument(commandLineArgs) {
+  for (let argumentIndex = 0; argumentIndex < commandLineArgs.length; argumentIndex += 1) {
+    const candidateArgument = commandLineArgs[argumentIndex];
+    if (VALUE_FLAGS.has(candidateArgument)) {
+      argumentIndex += 1;
+      continue;
+    }
+    if (!candidateArgument.startsWith('--')) {
+      return candidateArgument;
+    }
+  }
+  return null;
+}
+
+function buildSkipMessage(reason) {
+  if (reason === 'design-intent-file-absent') {
+    return [
+      'Audit skipped: docs/design-intent.json is missing.',
+      'Next step:',
+      '  - Fresh project: run `npx @ryuenn3123/agentic-senior-core init` to seed the design contract.',
+      '  - Existing project: run `npx @ryuenn3123/agentic-senior-core upgrade` to seed it without touching app code.',
+      'Then re-run this audit.',
+    ];
+  }
+  if (reason === 'anti-repeat-ledger-absent') {
+    return [
+      'Audit skipped: docs/design-intent.json is present but researchDossier metadata is absent.',
+      'Next step:',
+      '  - Run `npx @ryuenn3123/agentic-senior-core upgrade` to migrate the contract; the upgrade injects',
+      '    `researchDossier.metadata` and seeds the anti-repeat ledger from existing anchor, palette,',
+      '    motion, and typography fields without overwriting them.',
+      "  - Then run the design-research dossier prompt at `.agent-context/prompts/research-design.md`",
+      '    so the ledger and `researchVerifiedAt` get populated before the next UI work.',
+      'After that, re-run this audit to enforce the ledger against your CSS.',
+    ];
+  }
+  if (typeof reason === 'string' && reason.startsWith('design-intent-file-not-valid-json')) {
+    return [
+      'Audit skipped: docs/design-intent.json is present but cannot be parsed as JSON.',
+      `  ${reason}`,
+      'Next step: fix the JSON syntax, then re-run this audit.',
+    ];
+  }
+  return [`Audit skipped: ${reason || 'unknown reason'}`];
+}
+
+function printHumanReport(auditReport) {
+  console.log('===============================================');
+  console.log('  audit:design-anti-repeat');
+  console.log('===============================================');
+  console.log(`  Target directory:            ${auditReport.targetDirectoryPath}`);
+  console.log(`  Files scanned:               ${auditReport.filesScanned}`);
+  console.log(`  Typography violations:       ${auditReport.typographyViolationCount} (blocking)`);
+  console.log(`  Palette findings:            ${auditReport.paletteFindingCount} (${auditReport.paletteSeverity})`);
+  console.log(`  OKLCH distance threshold:    ${auditReport.oklchDistanceThreshold}`);
+  console.log('');
+
+  if (auditReport.skipped) {
+    for (const skipLine of buildSkipMessage(auditReport.reason)) {
+      console.log(`  ${skipLine}`);
+    }
+    return;
+  }
+
+  if (auditReport.typographyViolations.length > 0) {
+    console.log('  Typography violations (blocking):');
+    for (const violation of auditReport.typographyViolations) {
+      console.log(`    [${violation.kind}] ${violation.file}:${violation.line} ${violation.detail}`);
+    }
+    console.log('');
+  }
+
+  if (auditReport.paletteFindings.length > 0) {
+    console.log(`  Palette findings (${auditReport.paletteSeverity}):`);
+    for (const finding of auditReport.paletteFindings) {
+      console.log(`    [${finding.kind}] ${finding.file}:${finding.line} ${finding.detail}`);
+    }
+    console.log('');
+  }
+
+  if (auditReport.passed) {
+    console.log('  No blocking violations against the anti-repeat ledger.');
+    return;
+  }
+
+  const blockingPaletteCount = auditReport.paletteSeverity === 'blocking' ? auditReport.paletteFindingCount : 0;
+  console.log(`  ${auditReport.typographyViolationCount} typography violation(s) and ${blockingPaletteCount} palette violation(s) found; release blocked.`);
+}
+
+export async function runDesignAntiRepeatAuditCommand(commandLineArgs = []) {
+  if (commandLineArgs.includes('--help') || commandLineArgs.includes('-h')) {
+    console.log(buildHelpText());
+    return 0;
+  }
+
+  const shouldOutputJsonOnly = commandLineArgs.includes('--json');
+  const shouldTreatPaletteAsAdvisory = commandLineArgs.includes('--palette-advisory');
+  const oklchDistanceThreshold = readNumericFlag(commandLineArgs, '--threshold');
+  const targetDirectoryArgument = extractTargetDirectoryArgument(commandLineArgs);
+  const targetDirectoryPath = resolve(targetDirectoryArgument || process.cwd());
+
+  const auditReport = runTypographyPaletteAntiRepeatAudit({
+    repositoryRootPath: targetDirectoryPath,
+    treatPaletteAsAdvisory: shouldTreatPaletteAsAdvisory,
+    ...(typeof oklchDistanceThreshold === 'number' ? { oklchDistanceThreshold } : {}),
+  });
+  const auditReportWithRoot = { ...auditReport, targetDirectoryPath };
+
+  if (shouldOutputJsonOnly) {
+    process.stdout.write(`${JSON.stringify(auditReportWithRoot, null, 2)}\n`);
+    return auditReportWithRoot.passed ? 0 : 1;
+  }
+
+  printHumanReport(auditReportWithRoot);
+  return auditReportWithRoot.passed ? 0 : 1;
+}

package/lib/cli/commands/upgrade.mjs

@@ -464,6 +464,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       }
 
       console.log('\nRefreshed files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
+      console.log('\nNext-step suggestion (UI scope): run `npx @ryuenn3123/agentic-senior-core audit:design-anti-repeat` to scan CSS, SCSS, SASS, LESS, Tailwind config, and design-token files in this project for typography or palette values that match the anti-repeat ledger in docs/design-intent.json. Add it to your CI alongside `npm test` once the design dossier is populated.');
     } catch (error) {
       console.error('\n[FATAL] An error occurred during upgrade. Attempting automatic rollback...');
       try {

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

@@ -84,6 +84,28 @@ function buildPreviousMotionEntry(designIntentContract) {
   }];
 }
 
+function buildPreviousTypographyEntry(designIntentContract) {
+  if (!designIntentContract || typeof designIntentContract !== 'object') {
+    return [];
+  }
+  const tokenSystem = designIntentContract?.tokenSystem;
+  const typographyTokens = tokenSystem && typeof tokenSystem === 'object' ? tokenSystem.typographyTokens : null;
+  if (!typographyTokens || typeof typographyTokens !== 'object') {
+    return [];
+  }
+  const tokenEntries = Object.entries(typographyTokens)
+    .filter(([, value]) => typeof value === 'string' && value.trim().length > 0)
+    .map(([role, value]) => `${role}: ${value.trim()}`);
+  if (tokenEntries.length === 0) {
+    return [];
+  }
+  return [{
+    summary: tokenEntries.join('; '),
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-typography-trio',
+  }];
+}
+
 export function buildResearchDossierMetadata({
   designIntentContract = null,
   populateLedgerFromExistingContract = false,
@@ -99,6 +121,7 @@ export function buildResearchDossierMetadata({
       previousAnchors: [],
       previousPalettes: [],
       previousMotionSignatures: [],
+      previousTypographyChoices: [],
     },
     userExplicitRedesignBypassesFreshness: true,
     statusAwareValidation: {
@@ -116,6 +139,7 @@ export function buildResearchDossierMetadata({
     metadata.antiRepeatLedger.previousAnchors = buildPreviousAnchorEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
     metadata.antiRepeatLedger.previousPalettes = buildPreviousPaletteEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
     metadata.antiRepeatLedger.previousMotionSignatures = buildPreviousMotionEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
+    metadata.antiRepeatLedger.previousTypographyChoices = buildPreviousTypographyEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
   }
 
   return metadata;

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

@@ -12,7 +12,7 @@ const REQUIRED_SEED_STATUSES = [
   'seed-generated-during-init',
   'seed-generated-during-upgrade',
 ];
-const ANTI_REPEAT_LEDGER_CATEGORIES = ['previousAnchors', 'previousPalettes', 'previousMotionSignatures'];
+const ANTI_REPEAT_LEDGER_CATEGORIES = ['previousAnchors', 'previousPalettes', 'previousMotionSignatures', 'previousTypographyChoices'];
 
 function validateMetadataBaseShape(metadata, validationErrors) {
   if (

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

@@ -139,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 }),

package/lib/cli/utils.mjs

@@ -58,6 +58,7 @@ export function printUsage() {
   console.log('  agentic-senior-core optimize [target-directory] [--agent <copilot|claude|cursor|windsurf|gemini|codex|cline>] [--enable|--disable] [--show]');
   console.log('  agentic-senior-core mcp');
   console.log('  agentic-senior-core rollback [target-directory]');
+  console.log('  agentic-senior-core audit:design-anti-repeat [target-directory] [--json] [--palette-advisory] [--threshold <number>]');
   console.log('  agentic-senior-core --version');
   console.log('');
   console.log('Options:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -59,6 +59,7 @@
     "audit:cache-layer-contract": "node ./scripts/audit-cache-layer-contract.mjs",
     "audit:reflection-citations": "node ./scripts/audit-reflection-citations.mjs",
     "audit:caching-scope-hygiene": "node ./scripts/audit-caching-scope-hygiene.mjs",
+    "audit:typography-palette-anti-repeat": "node ./scripts/audit-typography-palette-anti-repeat.mjs",
     "audit:release-bundle": "node ./scripts/audit-release-bundle.mjs",
     "audit:file-size": "node ./scripts/audit-file-size.mjs",
     "audit:rule-id-uniqueness": "node ./scripts/audit-rule-id-uniqueness.mjs",
@@ -83,7 +84,7 @@
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "clean:local": "node ./scripts/clean-local-artifacts.mjs",
     "validate": "node ./scripts/validate.mjs",
-    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.test.mjs ./tests/migrate-rule-format.test.mjs ./tests/audit-caching-scope-hygiene.test.mjs ./tests/research-dossier-migration.test.mjs ./benchmarks/token-usage/lib/token-counter.test.mjs ./benchmarks/token-usage/lib/provider-cache-matrix.test.mjs ./benchmarks/token-usage/lib/cache-layer-contract.test.mjs ./benchmarks/token-usage/lib/cache-economics.test.mjs"
+    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.test.mjs ./tests/migrate-rule-format.test.mjs ./tests/audit-caching-scope-hygiene.test.mjs ./tests/research-dossier-migration.test.mjs ./tests/typography-palette-anti-repeat-audit.test.mjs ./tests/audit-design-anti-repeat-command.test.mjs ./benchmarks/token-usage/lib/token-counter.test.mjs ./benchmarks/token-usage/lib/provider-cache-matrix.test.mjs ./benchmarks/token-usage/lib/cache-layer-contract.test.mjs ./benchmarks/token-usage/lib/cache-economics.test.mjs"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.96.0",

package/scripts/audit-typography-palette-anti-repeat.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-typography-palette-anti-repeat.mjs
+ *
+ * Thin CLI wrapper around lib/cli/audits/typography-palette-anti-repeat-audit.mjs.
+ * The wrapper defaults to scanning the current working directory so it works
+ * for both repo-internal `npm run audit:typography-palette-anti-repeat` (npm
+ * sets cwd to the repo root) and direct invocation from a user project. The
+ * user-facing entry point is the `audit:design-anti-repeat` subcommand on
+ * the published bin (see lib/cli/commands/audit-design-anti-repeat.mjs).
+ *
+ * Usage:
+ *   node scripts/audit-typography-palette-anti-repeat.mjs
+ *   node scripts/audit-typography-palette-anti-repeat.mjs --json
+ *   node scripts/audit-typography-palette-anti-repeat.mjs --palette-advisory
+ *   node scripts/audit-typography-palette-anti-repeat.mjs --threshold 0.05
+ *   node scripts/audit-typography-palette-anti-repeat.mjs --root /path/to/project
+ *
+ * Default severity:
+ *   - Typography matches always block.
+ *   - Palette matches block by default. Pass --palette-advisory to opt a
+ *     project into advisory-only palette reporting (release stays unblocked
+ *     by palette findings; typography still blocks).
+ *
+ * Exit codes:
+ *   0 = no blocking violations
+ *   1 = at least one BOUNDARY_TYPOGRAPHY_LEDGER_VIOLATION or, in default
+ *       mode, BOUNDARY_PALETTE_LEDGER_VIOLATION
+ */
+
+import { resolve } from 'node:path';
+
+import { runTypographyPaletteAntiRepeatAudit } from '../lib/cli/audits/typography-palette-anti-repeat-audit.mjs';
+
+const COMMAND_LINE_ARGS = process.argv.slice(2);
+const SHOULD_OUTPUT_JSON_ONLY = COMMAND_LINE_ARGS.includes('--json');
+const SHOULD_TREAT_PALETTE_AS_ADVISORY = COMMAND_LINE_ARGS.includes('--palette-advisory');
+
+function readStringFlag(flagName) {
+  const flagIndex = COMMAND_LINE_ARGS.indexOf(flagName);
+  if (flagIndex === -1) {
+    return null;
+  }
+  const flagValue = COMMAND_LINE_ARGS[flagIndex + 1];
+  if (typeof flagValue !== 'string' || flagValue.length === 0 || flagValue.startsWith('--')) {
+    return null;
+  }
+  return flagValue;
+}
+
+function readNumericFlag(flagName) {
+  const stringValue = readStringFlag(flagName);
+  if (stringValue === null) {
+    return null;
+  }
+  const numericValue = Number(stringValue);
+  return Number.isFinite(numericValue) ? numericValue : null;
+}
+
+function main() {
+  const oklchDistanceThreshold = readNumericFlag('--threshold');
+  const explicitRootPath = readStringFlag('--root');
+  const repositoryRootPath = resolve(explicitRootPath || process.cwd());
+
+  const auditReport = runTypographyPaletteAntiRepeatAudit({
+    repositoryRootPath,
+    treatPaletteAsAdvisory: SHOULD_TREAT_PALETTE_AS_ADVISORY,
+    ...(typeof oklchDistanceThreshold === 'number' ? { oklchDistanceThreshold } : {}),
+  });
+
+  if (SHOULD_OUTPUT_JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify({ ...auditReport, repositoryRootPath }, null, 2)}\n`);
+    process.exit(auditReport.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:typography-palette-anti-repeat');
+  console.log('===============================================');
+  console.log(`  Target directory:            ${repositoryRootPath}`);
+  console.log(`  Files scanned:               ${auditReport.filesScanned}`);
+  console.log(`  Typography violations:       ${auditReport.typographyViolationCount} (blocking)`);
+  console.log(`  Palette findings:            ${auditReport.paletteFindingCount} (${auditReport.paletteSeverity})`);
+  console.log(`  OKLCH distance threshold:    ${auditReport.oklchDistanceThreshold}`);
+  console.log('');
+
+  if (auditReport.skipped) {
+    console.log(`  Audit skipped: ${auditReport.reason}`);
+    process.exit(0);
+  }
+
+  if (auditReport.typographyViolations.length > 0) {
+    console.log('  Typography violations (blocking):');
+    for (const violation of auditReport.typographyViolations) {
+      console.log(`    [${violation.kind}] ${violation.file}:${violation.line} ${violation.detail}`);
+    }
+    console.log('');
+  }
+
+  if (auditReport.paletteFindings.length > 0) {
+    console.log(`  Palette findings (${auditReport.paletteSeverity}):`);
+    for (const finding of auditReport.paletteFindings) {
+      console.log(`    [${finding.kind}] ${finding.file}:${finding.line} ${finding.detail}`);
+    }
+    console.log('');
+  }
+
+  if (auditReport.passed) {
+    console.log('  No blocking violations against the anti-repeat ledger.');
+    process.exit(0);
+  }
+  const blockingPaletteCount = auditReport.paletteSeverity === 'blocking' ? auditReport.paletteFindingCount : 0;
+  console.log(`  ${auditReport.typographyViolationCount} typography violation(s) and ${blockingPaletteCount} palette violation(s) found; release blocked.`);
+  process.exit(1);
+}
+
+if (process.argv[1] && (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-typography-palette-anti-repeat.mjs'))) {
+  main();
+}

package/scripts/documentation-boundary-audit.mjs

@@ -74,6 +74,19 @@ const BOUNDARY_RULES = [
       'README.md',
     ],
     trigger(filePath) {
+      // Path-based exclusion: design-contract JSON shape lives under
+      // lib/cli/project-scaffolder/. Files like research-dossier-migration.mjs
+      // describe agent-prompt JSON contract migrations, not database schema
+      // or persistent-store migrations, so they must not trigger this boundary
+      // even when the filename contains the words "schema" or "migration".
+      // Tests for those design-contract migrations are excluded for the same
+      // reason.
+      if (filePath.startsWith('lib/cli/project-scaffolder/')) {
+        return false;
+      }
+      if (filePath.startsWith('tests/') && /research-dossier|design-contract/i.test(filePath)) {
+        return false;
+      }
       return !isDocumentationFilePath(filePath)
         && /(database|schema|migration|repository|sql|prisma|typeorm|knex)/i.test(filePath);
     },

package/scripts/release-gate/static-checks.mjs

@@ -79,7 +79,12 @@ export function runStaticReleaseChecks(results, diagnostics) {
         stackFileName: 'agent-decision-runtime.md',
         blueprintFileName: 'agent-decision-architecture.md',
       },
-      status: 'release-gate-seed-validation',
+      // Seed status so `tokenContinuityClassification: pending-research`
+      // is a valid placeholder. This probe asserts seed-shape completeness,
+      // not active-contract behavior; an agent or user fills the contract
+      // with anchor-derived / continuity-retained / newly-introduced once
+      // the dossier is filled.
+      status: 'seed-needs-design-synthesis',
     }));
     const designContractIssues = validateDesignContractCompleteness(designIntentSeed);
 

package/scripts/validate/config.mjs

@@ -376,6 +376,13 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'Anti-Repeat Ledger Gate',
       'previousAnchors',
       'previousMotionSignatures',
+      'Dimensional split',
+      'typographyClusters',
+      'paletteClusters',
+      'layoutClusters',
+      'motionClusters',
+      'imageryClusters',
+      'tokenContinuityClassification',
     ],
   },
   {

package/scripts/validate.mjs

@@ -20,6 +20,7 @@ import { fileURLToPath } from 'node:url';
 import { ALLOWED_SEVERITIES } from './validate/config.mjs';
 import { runCacheLayerContractAudit } from './audit-cache-layer-contract.mjs';
 import { runCachingScopeHygieneAudit } from './audit-caching-scope-hygiene.mjs';
+import { runTypographyPaletteAntiRepeatAudit } from '../lib/cli/audits/typography-palette-anti-repeat-audit.mjs';
 import { runAuditFileSize } from './audit-file-size.mjs';
 import { runReflectionCitationAudit } from './audit-reflection-citations.mjs';
 import { runReleaseBundleAudit } from './audit-release-bundle.mjs';
@@ -153,6 +154,9 @@ async function validateRequiredFiles() {
     'scripts/explain-on-demand-audit.mjs',
     'scripts/single-source-lazy-loading-audit.mjs',
     'scripts/audit-cache-layer-contract.mjs',
+    'scripts/audit-typography-palette-anti-repeat.mjs',
+    'lib/cli/audits/typography-palette-anti-repeat-audit.mjs',
+    'lib/cli/commands/audit-design-anti-repeat.mjs',
     'scripts/sync-thin-adapters.mjs',
     'scripts/v3-purge-audit.mjs',
     'scripts/release-gate.mjs',
@@ -569,6 +573,34 @@ async function validateCachingScopeHygieneAudit() {
   }
 }
 
+async function validateTypographyPaletteAntiRepeatAudit() {
+  console.log('\nChecking typography and palette anti-repeat ledger (audit:typography-palette-anti-repeat)...');
+  const report = runTypographyPaletteAntiRepeatAudit({ repositoryRootPath: ROOT_DIR });
+
+  if (report.skipped) {
+    pass(`Typography/palette anti-repeat audit skipped: ${report.reason}`);
+    return;
+  }
+
+  if (report.passed) {
+    pass(`Typography/palette anti-repeat audit clean: ${report.filesScanned} CSS/token file(s) scanned, 0 blocking typography violation(s), ${report.paletteFindingCount} palette finding(s) (${report.paletteSeverity})`);
+    return;
+  }
+
+  for (const violation of report.typographyViolations) {
+    fail(`Typography ledger violation [${violation.kind}] in ${violation.file}:${violation.line}: ${violation.detail}`);
+  }
+  if (report.paletteSeverity === 'blocking') {
+    for (const finding of report.paletteFindings) {
+      fail(`Palette ledger violation [${finding.kind}] in ${finding.file}:${finding.line}: ${finding.detail}`);
+    }
+  } else {
+    for (const finding of report.paletteFindings) {
+      warn(`Palette ledger advisory [${finding.kind}] in ${finding.file}:${finding.line}: ${finding.detail}`);
+    }
+  }
+}
+
 async function validateReleaseBundleAudit() {
   console.log('\nChecking release benchmark bundle (audit:release-bundle)...');
   const report = runReleaseBundleAudit();
@@ -666,6 +698,7 @@ async function main() {
   await validateCacheLayerContractAudit();
   await validateReflectionCitationAudit();
   await validateCachingScopeHygieneAudit();
+  await validateTypographyPaletteAntiRepeatAudit();
   await validateReleaseBundleAudit();
   await validateFileSizeAudit();
   await validateRuleIdUniquenessAudit();