@ryuenn3123/agentic-senior-core 4.0.2 → 4.1.0

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/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,8 +1,8 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "type": "module",
-  "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
+  "description": "Change your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
     "agentic-senior-core": "bin/agentic-senior-core.js"
   },
@@ -59,10 +59,10 @@
     "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",
-    "audit:v3-purge": "node ./scripts/v3-purge-audit.mjs",
     "build:release-bundle": "node ./scripts/build-release-benchmark-bundle.mjs",
     "sync:adapters": "node ./scripts/sync-thin-adapters.mjs",
     "check:adapters": "node ./scripts/sync-thin-adapters.mjs --check",
@@ -83,7 +83,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/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-cache-layer-contract.mjs

@@ -5,6 +5,11 @@
  * Phase 2 cache-layer integrity gate. Validates provider cache metadata,
  * fixture segmentation, and the emitted cache simulation JSON without calling
  * provider APIs.
+ *
+ * Boundary: this audit covers the TECHNICAL contract (provider matrix,
+ * layer definitions, fixture segmentation, simulation result JSON shape).
+ * For public-prose hygiene around caching saving figures see
+ * audit-caching-scope-hygiene.mjs.
  */
 
 import { existsSync, readFileSync } from 'node:fs';

package/scripts/audit-caching-scope-hygiene.mjs

@@ -9,6 +9,11 @@
  * that each claim is integration-scoped per `docs/architecture/decisions-foundation.md`
  * D4 "Per-Tool Caching Scope Matrix".
  *
+ * Boundary: this audit covers PUBLIC-PROSE hygiene only (preventing
+ * universal "X% caching saving" claims that mix integration modes). For the
+ * technical provider/fixture/result-JSON contract see
+ * audit-cache-layer-contract.mjs.
+ *
  * The rule: never publish a single universal "X% caching saving" figure that
  * mixes integration modes. Every numerical caching saving claim on a public
  * surface must either:

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/clean-local-artifacts.mjs

@@ -15,7 +15,6 @@ const LOCAL_ARTIFACT_PATHS = [
   '.zed',
   '.agentic-backup',
   '.agent-context/state/active-memory.json',
-  '.agent-context/state/v3-purge-audit.json',
   '.agent-context/state/llm-judge-report.json',
   '.agent-context/state/benchmark-analysis.json',
   '.agent-context/state/benchmark-evidence-bundle.json',