From a39e02fb1306eb301f5af755196d91419b556f3f Mon Sep 17 00:00:00 2001
From: Jake Strawn <jake.strawn@gmail.com>
Date: Thu, 26 Mar 2026 20:39:37 -0400
Subject: [PATCH] feat: allow enterprises to customize health scoring weights
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add optional scoring.weights config section to helixir.mcp.json
that lets enterprise teams apply per-dimension weight multipliers
to health scores. Accessibility-first teams can weight that
dimension 3× while rapid-prototyping teams can downweight it 0.5×.

- Add ScoringWeights and ScoringConfig interfaces to McpWcConfig
- Parse and validate scoring.weights in loadConfig() (positive
  numbers only; warn and discard invalid values)
- Export DIMENSION_WEIGHT_KEYS mapping from dimensions.ts
- Apply multipliers via getEffectiveWeight() in
  scoreComponentMultiDimensional()
- Default multiplier is 1.0 (fully backward-compatible)
- Document all 14 dimension keys in README with examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md                                     |  67 +++
 packages/core/src/config.ts                   |  86 +++
 packages/core/src/handlers/dimensions.ts      |  23 +
 packages/core/src/handlers/health.ts          |  37 +-
 .../configurable-health-scoring.test.ts       | 497 ++++++++++++++++++
 5 files changed, 707 insertions(+), 3 deletions(-)
 create mode 100644 tests/handlers/configurable-health-scoring.test.ts

diff --git a/README.md b/README.md
index 6feb3c9..4043c0c 100644
--- a/README.md
+++ b/README.md
@@ -455,6 +455,7 @@ Place this file at the root of your component library project (or wherever `MCP_
 | `tokensPath`       | `string \| null` | `null`                   | Path to a design tokens JSON file. Set to `null` to disable token tools.                                                                                                                                                                                              |
 | `cdnBase`          | `string \| null` | `null`                   | Base URL prepended to component paths when generating CDN `<script>` and `<link>` tags in `suggest_usage` output (e.g. `"https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2/cdn"`). Does not affect `resolve_cdn_cem`. Set to `null` to disable CDN suggestions. |
 | `watch`            | `boolean`        | `false`                  | When `true`, HELiXiR automatically reloads the CEM on file changes.                                                                                                                                                                                                   |
+| `scoring`          | `object`         | `undefined`              | Optional scoring configuration for customizing health dimension weights. See [Configurable Health Scoring Weights](#configurable-health-scoring-weights).                                                                                                              |
 
 **Full example:**
 
@@ -470,6 +471,72 @@ Place this file at the root of your component library project (or wherever `MCP_
 }
 ```
 
+### Configurable Health Scoring Weights
+
+Enterprise teams have different priorities. A design system team may weight accessibility at 3× while a rapid-prototyping team may treat it as lower priority. The `scoring.weights` config section lets you adjust per-dimension weight multipliers:
+
+```json
+{
+  "scoring": {
+    "weights": {
+      "documentation": 1.0,
+      "accessibility": 1.5,
+      "naming": 1.0,
+      "apiConsistency": 1.0,
+      "cssArchitecture": 1.0,
+      "cemSourceFidelity": 0.5
+    }
+  }
+}
+```
+
+Each value is a **positive multiplier** applied to that dimension's base weight (e.g. `1.5` = 50% more influence; `0.5` = half influence). Omitted keys default to `1.0` (unchanged). Setting a key to `0` or a negative number is rejected with a warning.
+
+**Supported keys and their dimensions:**
+
+| Config Key          | Health Dimension         | Default Weight |
+| ------------------- | ------------------------ | -------------- |
+| `documentation`     | CEM Completeness         | 15             |
+| `accessibility`     | Accessibility            | 10             |
+| `typeCoverage`      | Type Coverage            | 10             |
+| `apiConsistency`    | API Surface Quality      | 10             |
+| `cemSourceFidelity` | CEM-Source Fidelity      | 10             |
+| `testCoverage`      | Test Coverage            | 10             |
+| `cssArchitecture`   | CSS Architecture         | 5              |
+| `eventArchitecture` | Event Architecture       | 5              |
+| `slotArchitecture`  | Slot Architecture        | 5              |
+| `bundleSize`        | Bundle Size              | 5              |
+| `storyCoverage`     | Story Coverage           | 5              |
+| `naming`            | Naming Consistency       | 5              |
+| `performance`       | Performance              | 5              |
+| `drupalReadiness`   | Drupal Readiness         | 5              |
+
+**Accessibility-first team example:**
+```json
+{
+  "scoring": {
+    "weights": {
+      "accessibility": 3.0,
+      "testCoverage": 2.0,
+      "cemSourceFidelity": 0.5
+    }
+  }
+}
+```
+
+**Rapid-prototyping team example:**
+```json
+{
+  "scoring": {
+    "weights": {
+      "documentation": 0.5,
+      "testCoverage": 0.5,
+      "accessibility": 0.5
+    }
+  }
+}
+```
+
 ### Environment Variables
 
 Environment variables override all config file values. Useful for CI or when pointing the same server at different libraries.
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
index b35efec..824fb0f 100644
--- a/packages/core/src/config.ts
+++ b/packages/core/src/config.ts
@@ -2,6 +2,51 @@ import { readFileSync, existsSync } from 'fs';
 import { resolve } from 'path';
 import { discoverCemPath, FRIENDLY_CEM_ERROR } from './shared/discovery.js';
 
+/**
+ * Weight multipliers for each health scoring dimension.
+ * Each key maps to a dimension in the DIMENSION_REGISTRY.
+ * Values are positive multipliers (1.0 = base weight, 2.0 = double, 0.5 = half).
+ */
+export interface ScoringWeights {
+  /** CEM Completeness dimension */
+  readonly documentation?: number;
+  /** Accessibility dimension */
+  readonly accessibility?: number;
+  /** Type Coverage dimension */
+  readonly typeCoverage?: number;
+  /** API Surface Quality dimension */
+  readonly apiConsistency?: number;
+  /** CSS Architecture dimension */
+  readonly cssArchitecture?: number;
+  /** Event Architecture dimension */
+  readonly eventArchitecture?: number;
+  /** Test Coverage dimension */
+  readonly testCoverage?: number;
+  /** Bundle Size dimension */
+  readonly bundleSize?: number;
+  /** Story Coverage dimension */
+  readonly storyCoverage?: number;
+  /** Performance dimension */
+  readonly performance?: number;
+  /** Drupal Readiness dimension */
+  readonly drupalReadiness?: number;
+  /** CEM-Source Fidelity dimension */
+  readonly cemSourceFidelity?: number;
+  /** Slot Architecture dimension */
+  readonly slotArchitecture?: number;
+  /** Naming Consistency dimension */
+  readonly naming?: number;
+}
+
+/**
+ * Enterprise scoring configuration.
+ * Allows teams to adjust dimension weights to match their priorities.
+ */
+export interface ScoringConfig {
+  /** Per-dimension weight multipliers. Missing keys default to 1.0. */
+  readonly weights?: ScoringWeights;
+}
+
 export interface McpWcConfig {
   readonly cemPath: string;
   readonly projectRoot: string;
@@ -13,11 +58,44 @@ export interface McpWcConfig {
   readonly cdnAutoloader?: string | null;
   readonly cdnStylesheet?: string | null;
   readonly watch: boolean;
+  /** Optional scoring configuration for customizing health dimension weights. */
+  readonly scoring?: ScoringConfig;
 }
 
 /** Mutable version used internally during config construction. */
 type McpWcConfigMutable = { -readonly [K in keyof McpWcConfig]: McpWcConfig[K] };
 
+/**
+ * Validates and sanitizes the scoring.weights section from config file.
+ * Invalid values (non-positive numbers, non-numbers) are discarded with a warning.
+ */
+function validateScoringWeights(raw: unknown): ScoringWeights | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const result: Record<string, number> = {};
+  for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof val === 'number' && val > 0) {
+      result[key] = val;
+    } else if (val !== undefined) {
+      process.stderr.write(
+        `[helixir] Warning: scoring.weights.${key} must be a positive number. Ignoring.\n`,
+      );
+    }
+  }
+  return Object.keys(result).length > 0 ? (result as ScoringWeights) : undefined;
+}
+
+/**
+ * Parses the scoring section from the config file.
+ * Always returns a ScoringConfig object (never undefined) when called.
+ */
+function parseScoringConfig(raw: unknown): ScoringConfig {
+  if (typeof raw !== 'object' || raw === null) return {};
+  const scoringRaw = raw as Record<string, unknown>;
+  if (scoringRaw['weights'] === undefined) return {};
+  const weights = validateScoringWeights(scoringRaw['weights']);
+  return weights !== undefined ? { weights } : {};
+}
+
 const defaults: McpWcConfig = {
   cemPath: 'custom-elements.json',
   projectRoot: process.cwd(),
@@ -61,8 +139,16 @@ export function loadConfig(): Readonly<McpWcConfig> {
   // Prevent config file from overriding projectRoot (circular dependency).
   const safeFileConfig: Omit<Partial<McpWcConfig>, 'projectRoot'> = { ...fileConfig };
   delete (safeFileConfig as Record<string, unknown>)['projectRoot'];
+  // scoring needs special validation — extract before mass-assign and apply separately
+  const rawScoringFromFile = (safeFileConfig as Record<string, unknown>)['scoring'];
+  delete (safeFileConfig as Record<string, unknown>)['scoring'];
   Object.assign(config, safeFileConfig);
 
+  // Apply validated scoring config (weights must be positive numbers)
+  if (rawScoringFromFile !== undefined) {
+    config.scoring = parseScoringConfig(rawScoringFromFile);
+  }
+
   // Auto-discover cemPath if not explicitly configured via env var or config file
   const cemPathExplicit = process.env['MCP_WC_CEM_PATH'] !== undefined || fileCemPath !== undefined;
 
diff --git a/packages/core/src/handlers/dimensions.ts b/packages/core/src/handlers/dimensions.ts
index 195494c..2bda265 100644
--- a/packages/core/src/handlers/dimensions.ts
+++ b/packages/core/src/handlers/dimensions.ts
@@ -158,6 +158,29 @@ export const DIMENSION_CLASSIFICATION = {
 
 export const TOTAL_WEIGHT = DIMENSION_REGISTRY.reduce((sum, d) => sum + d.weight, 0);
 
+/**
+ * Maps scoring config keys (from helixir.mcp.json `scoring.weights`)
+ * to their corresponding dimension names in the DIMENSION_REGISTRY.
+ *
+ * Used to apply per-enterprise weight multipliers to health scoring.
+ */
+export const DIMENSION_WEIGHT_KEYS: Readonly<Record<string, string>> = {
+  documentation: 'CEM Completeness',
+  accessibility: 'Accessibility',
+  typeCoverage: 'Type Coverage',
+  apiConsistency: 'API Surface Quality',
+  cssArchitecture: 'CSS Architecture',
+  eventArchitecture: 'Event Architecture',
+  testCoverage: 'Test Coverage',
+  bundleSize: 'Bundle Size',
+  storyCoverage: 'Story Coverage',
+  performance: 'Performance',
+  drupalReadiness: 'Drupal Readiness',
+  cemSourceFidelity: 'CEM-Source Fidelity',
+  slotArchitecture: 'Slot Architecture',
+  naming: 'Naming Consistency',
+} as const;
+
 // ─── Grade Thresholds ────────────────────────────────────────────────────────
 
 interface GradeThreshold {
diff --git a/packages/core/src/handlers/health.ts b/packages/core/src/handlers/health.ts
index 216b1a2..a661f69 100644
--- a/packages/core/src/handlers/health.ts
+++ b/packages/core/src/handlers/health.ts
@@ -21,12 +21,14 @@ import {
 } from './analyzers/naming-consistency.js';
 import {
   DIMENSION_REGISTRY,
+  DIMENSION_WEIGHT_KEYS,
   calculateGrade,
   computeWeightedScore,
   type ConfidenceLevel,
   type DimensionResult,
   type SubMetric,
 } from './dimensions.js';
+import type { ScoringWeights } from '../config.js';
 
 // ─── Return types ────────────────────────────────────────────────────────────
 
@@ -740,6 +742,31 @@ function scoreCemCompleteness(decl: CemDeclaration): { score: number; subMetrics
   return { score, subMetrics };
 }
 
+/**
+ * Returns the effective weight for a dimension, applying any multiplier
+ * from the config's `scoring.weights` section.
+ *
+ * @param baseWeight - The base weight from DIMENSION_REGISTRY
+ * @param dimensionName - The dimension name (e.g. 'CEM Completeness')
+ * @param weights - Optional scoring weights from config
+ * @returns The base weight multiplied by the configured multiplier (defaults to 1.0)
+ */
+function getEffectiveWeight(
+  baseWeight: number,
+  dimensionName: string,
+  weights: ScoringWeights | undefined,
+): number {
+  if (!weights) return baseWeight;
+  // Find the config key that maps to this dimension name
+  for (const [key, name] of Object.entries(DIMENSION_WEIGHT_KEYS)) {
+    if (name === dimensionName) {
+      const multiplier = (weights as Record<string, number | undefined>)[key];
+      return multiplier !== undefined ? baseWeight * multiplier : baseWeight;
+    }
+  }
+  return baseWeight;
+}
+
 /**
  * Scores a component across all 11 dimensions using the enterprise grade algorithm.
  * CEM-native dimensions are computed from the declaration.
@@ -768,7 +795,11 @@ export async function scoreComponentMultiDimensional(
     // No history available — external dimensions will be untested
   }
 
+  const scoringWeights = config.scoring?.weights;
+
   for (const def of DIMENSION_REGISTRY) {
+    const effectiveWeight = getEffectiveWeight(def.weight, def.name, scoringWeights);
+
     if (def.source === 'cem-native') {
       const result = await scoreCemNativeDimension(
         def.name,
@@ -782,7 +813,7 @@ export async function scoreComponentMultiDimensional(
       dimensions.push({
         name: def.name,
         score: result.score,
-        weight: def.weight,
+        weight: effectiveWeight,
         tier: def.tier,
         confidence: result.confidence,
         measured: !notApplicable,
@@ -795,7 +826,7 @@ export async function scoreComponentMultiDimensional(
         dimensions.push({
           name: def.name,
           score: historyEntry.score,
-          weight: def.weight,
+          weight: effectiveWeight,
           tier: def.tier,
           confidence: (historyEntry.confidence as 'verified' | 'heuristic') ?? 'verified',
           measured: true,
@@ -804,7 +835,7 @@ export async function scoreComponentMultiDimensional(
         dimensions.push({
           name: def.name,
           score: 0,
-          weight: def.weight,
+          weight: effectiveWeight,
           tier: def.tier,
           confidence: 'untested',
           measured: false,
diff --git a/tests/handlers/configurable-health-scoring.test.ts b/tests/handlers/configurable-health-scoring.test.ts
new file mode 100644
index 0000000..e5cb49c
--- /dev/null
+++ b/tests/handlers/configurable-health-scoring.test.ts
@@ -0,0 +1,497 @@
+/**
+ * Tests for configurable health scoring weights.
+ *
+ * Verifies that:
+ * - Custom weight multipliers in config.scoring.weights are applied to dimension weights
+ * - Default behavior (all weights 1.0) is backward-compatible
+ * - Only specified dimensions get their weights modified
+ * - All 14 dimension config keys are supported
+ * - Invalid/negative weights are rejected with a warning
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import type { McpWcConfig } from '../../packages/core/src/config.js';
+import { loadConfig } from '../../packages/core/src/config.js';
+import {
+  scoreComponentMultiDimensional,
+} from '../../packages/core/src/handlers/health.js';
+import {
+  DIMENSION_REGISTRY,
+  DIMENSION_WEIGHT_KEYS,
+} from '../../packages/core/src/handlers/dimensions.js';
+import type { CemDeclaration } from '../../packages/core/src/handlers/cem.js';
+
+const NO_HISTORY_DIR = '/nonexistent-health-history-scoring-test';
+
+function makeConfig(overrides?: Partial<McpWcConfig>): McpWcConfig {
+  return {
+    cemPath: 'custom-elements.json',
+    projectRoot: '/',
+    componentPrefix: '',
+    healthHistoryDir: NO_HISTORY_DIR,
+    tsconfigPath: 'tsconfig.json',
+    tokensPath: null,
+    cdnBase: null,
+    watch: false,
+    ...overrides,
+  };
+}
+
+// A simple but reasonably-documented component for stable testing
+const SIMPLE_DECL: CemDeclaration = {
+  kind: 'class',
+  name: 'TestComponent',
+  tagName: 'test-component',
+  description: 'A test component.',
+  members: [
+    {
+      kind: 'field',
+      name: 'value',
+      type: { text: 'string' },
+      description: 'The value.',
+      attribute: 'value',
+    },
+  ],
+  events: [{ name: 'change', type: { text: 'CustomEvent' }, description: 'Change event.' }],
+  slots: [{ name: '', description: 'Default slot.' }],
+  cssParts: [{ name: 'base', description: 'Base part.' }],
+};
+
+// A component with no accessibility signals — useful for weight-impact tests
+const LOW_A11Y_DECL: CemDeclaration = {
+  kind: 'class',
+  name: 'LowA11y',
+  tagName: 'low-a11y',
+  description: 'A component with poor accessibility.',
+  members: [
+    { kind: 'field', name: 'value', type: { text: 'string' }, description: 'Some value.' },
+  ],
+};
+
+// ─── DIMENSION_WEIGHT_KEYS mapping ───────────────────────────────────────────
+
+describe('DIMENSION_WEIGHT_KEYS', () => {
+  it('exports a mapping from config key to dimension name', () => {
+    expect(DIMENSION_WEIGHT_KEYS).toBeDefined();
+    expect(typeof DIMENSION_WEIGHT_KEYS).toBe('object');
+  });
+
+  it('maps documentation → CEM Completeness', () => {
+    expect(DIMENSION_WEIGHT_KEYS['documentation']).toBe('CEM Completeness');
+  });
+
+  it('maps accessibility → Accessibility', () => {
+    expect(DIMENSION_WEIGHT_KEYS['accessibility']).toBe('Accessibility');
+  });
+
+  it('maps naming → Naming Consistency', () => {
+    expect(DIMENSION_WEIGHT_KEYS['naming']).toBe('Naming Consistency');
+  });
+
+  it('maps apiConsistency → API Surface Quality', () => {
+    expect(DIMENSION_WEIGHT_KEYS['apiConsistency']).toBe('API Surface Quality');
+  });
+
+  it('maps cssArchitecture → CSS Architecture', () => {
+    expect(DIMENSION_WEIGHT_KEYS['cssArchitecture']).toBe('CSS Architecture');
+  });
+
+  it('maps cemSourceFidelity → CEM-Source Fidelity', () => {
+    expect(DIMENSION_WEIGHT_KEYS['cemSourceFidelity']).toBe('CEM-Source Fidelity');
+  });
+
+  it('maps typeCoverage → Type Coverage', () => {
+    expect(DIMENSION_WEIGHT_KEYS['typeCoverage']).toBe('Type Coverage');
+  });
+
+  it('maps eventArchitecture → Event Architecture', () => {
+    expect(DIMENSION_WEIGHT_KEYS['eventArchitecture']).toBe('Event Architecture');
+  });
+
+  it('maps testCoverage → Test Coverage', () => {
+    expect(DIMENSION_WEIGHT_KEYS['testCoverage']).toBe('Test Coverage');
+  });
+
+  it('maps bundleSize → Bundle Size', () => {
+    expect(DIMENSION_WEIGHT_KEYS['bundleSize']).toBe('Bundle Size');
+  });
+
+  it('maps storyCoverage → Story Coverage', () => {
+    expect(DIMENSION_WEIGHT_KEYS['storyCoverage']).toBe('Story Coverage');
+  });
+
+  it('maps performance → Performance', () => {
+    expect(DIMENSION_WEIGHT_KEYS['performance']).toBe('Performance');
+  });
+
+  it('maps drupalReadiness → Drupal Readiness', () => {
+    expect(DIMENSION_WEIGHT_KEYS['drupalReadiness']).toBe('Drupal Readiness');
+  });
+
+  it('maps slotArchitecture → Slot Architecture', () => {
+    expect(DIMENSION_WEIGHT_KEYS['slotArchitecture']).toBe('Slot Architecture');
+  });
+
+  it('covers all 14 dimensions in the DIMENSION_REGISTRY', () => {
+    const mappedDimensions = new Set(Object.values(DIMENSION_WEIGHT_KEYS));
+    const registryDimensions = new Set(DIMENSION_REGISTRY.map((d) => d.name));
+    // Every dimension in the registry should have a config key
+    for (const name of registryDimensions) {
+      expect(mappedDimensions.has(name)).toBe(true);
+    }
+  });
+});
+
+// ─── scoreComponentMultiDimensional with custom weights ───────────────────────
+
+describe('scoreComponentMultiDimensional — custom weights', () => {
+  it('uses base dimension weights when no scoring config provided', async () => {
+    const config = makeConfig();
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    for (const dim of result.dimensions) {
+      const registryEntry = DIMENSION_REGISTRY.find((d) => d.name === dim.name);
+      expect(registryEntry).toBeDefined();
+      expect(dim.weight).toBe(registryEntry!.weight);
+    }
+  });
+
+  it('uses base dimension weights when scoring config is empty object', async () => {
+    const config = makeConfig({ scoring: {} });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    for (const dim of result.dimensions) {
+      const registryEntry = DIMENSION_REGISTRY.find((d) => d.name === dim.name);
+      expect(dim.weight).toBe(registryEntry!.weight);
+    }
+  });
+
+  it('uses base dimension weights when scoring.weights is empty object', async () => {
+    const config = makeConfig({ scoring: { weights: {} } });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    for (const dim of result.dimensions) {
+      const registryEntry = DIMENSION_REGISTRY.find((d) => d.name === dim.name);
+      expect(dim.weight).toBe(registryEntry!.weight);
+    }
+  });
+
+  it('applies accessibility multiplier to Accessibility dimension weight', async () => {
+    const config = makeConfig({ scoring: { weights: { accessibility: 2.0 } } });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    const accessibilityDim = result.dimensions.find((d) => d.name === 'Accessibility');
+    const baseWeight = DIMENSION_REGISTRY.find((d) => d.name === 'Accessibility')!.weight;
+
+    expect(accessibilityDim).toBeDefined();
+    expect(accessibilityDim!.weight).toBe(baseWeight * 2.0);
+  });
+
+  it('applies documentation multiplier to CEM Completeness dimension weight', async () => {
+    const config = makeConfig({ scoring: { weights: { documentation: 1.5 } } });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    const dim = result.dimensions.find((d) => d.name === 'CEM Completeness');
+    const baseWeight = DIMENSION_REGISTRY.find((d) => d.name === 'CEM Completeness')!.weight;
+
+    expect(dim).toBeDefined();
+    expect(dim!.weight).toBeCloseTo(baseWeight * 1.5);
+  });
+
+  it('applies cemSourceFidelity multiplier to CEM-Source Fidelity dimension weight', async () => {
+    const config = makeConfig({ scoring: { weights: { cemSourceFidelity: 0.5 } } });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    const dim = result.dimensions.find((d) => d.name === 'CEM-Source Fidelity');
+    const baseWeight = DIMENSION_REGISTRY.find((d) => d.name === 'CEM-Source Fidelity')!.weight;
+
+    expect(dim).toBeDefined();
+    expect(dim!.weight).toBeCloseTo(baseWeight * 0.5);
+  });
+
+  it('only modifies specified dimensions; other dimensions keep base weights', async () => {
+    const config = makeConfig({ scoring: { weights: { accessibility: 3.0 } } });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    // Accessibility gets the multiplier
+    const accessibilityDim = result.dimensions.find((d) => d.name === 'Accessibility');
+    const accessibilityBase = DIMENSION_REGISTRY.find((d) => d.name === 'Accessibility')!.weight;
+    expect(accessibilityDim!.weight).toBe(accessibilityBase * 3.0);
+
+    // All other dimensions keep base weight
+    const otherDims = result.dimensions.filter((d) => d.name !== 'Accessibility');
+    for (const dim of otherDims) {
+      const registryEntry = DIMENSION_REGISTRY.find((d) => d.name === dim.name);
+      expect(dim.weight).toBe(registryEntry!.weight);
+    }
+  });
+
+  it('multiplier of 1.0 produces same result as no weight configured', async () => {
+    const baseConfig = makeConfig();
+    const explicitOneConfig = makeConfig({
+      scoring: { weights: { documentation: 1.0, accessibility: 1.0 } },
+    });
+
+    const baseResult = await scoreComponentMultiDimensional(baseConfig, SIMPLE_DECL);
+    const explicitOneResult = await scoreComponentMultiDimensional(explicitOneConfig, SIMPLE_DECL);
+
+    expect(explicitOneResult.score).toBe(baseResult.score);
+  });
+
+  it('higher weight on low-scoring dimension lowers the final score', async () => {
+    const baseConfig = makeConfig();
+    const highA11yConfig = makeConfig({ scoring: { weights: { accessibility: 5.0 } } });
+
+    const baseResult = await scoreComponentMultiDimensional(baseConfig, LOW_A11Y_DECL);
+    const highA11yResult = await scoreComponentMultiDimensional(highA11yConfig, LOW_A11Y_DECL);
+
+    const baseA11yDim = baseResult.dimensions.find((d) => d.name === 'Accessibility');
+    const highA11yDim = highA11yResult.dimensions.find((d) => d.name === 'Accessibility');
+
+    // Both have the same accessibility score
+    expect(baseA11yDim!.score).toBe(highA11yDim!.score);
+
+    // When accessibility scores poorly, increasing its weight should lower the final score
+    // (or at minimum not raise it)
+    if (baseA11yDim!.score < 50) {
+      expect(highA11yResult.score).toBeLessThanOrEqual(baseResult.score);
+    }
+  });
+
+  it('lower weight on a dimension reduces its impact on the final score', async () => {
+    const baseConfig = makeConfig();
+    const lowDocConfig = makeConfig({ scoring: { weights: { documentation: 0.1 } } });
+
+    const baseResult = await scoreComponentMultiDimensional(baseConfig, LOW_A11Y_DECL);
+    const lowDocResult = await scoreComponentMultiDimensional(lowDocConfig, LOW_A11Y_DECL);
+
+    // The two scores should differ
+    expect(lowDocResult.score).not.toBeNaN();
+    expect(lowDocResult.score).toBeGreaterThanOrEqual(0);
+    expect(lowDocResult.score).toBeLessThanOrEqual(100);
+
+    // The CEM Completeness weight should be reduced
+    const cemDim = lowDocResult.dimensions.find((d) => d.name === 'CEM Completeness');
+    const cemBase = DIMENSION_REGISTRY.find((d) => d.name === 'CEM Completeness')!.weight;
+    expect(cemDim!.weight).toBeCloseTo(cemBase * 0.1);
+  });
+
+  it('multiple weight overrides all apply simultaneously', async () => {
+    const config = makeConfig({
+      scoring: {
+        weights: {
+          documentation: 2.0,
+          accessibility: 0.5,
+          naming: 3.0,
+        },
+      },
+    });
+    const result = await scoreComponentMultiDimensional(config, SIMPLE_DECL);
+
+    const docDim = result.dimensions.find((d) => d.name === 'CEM Completeness');
+    const a11yDim = result.dimensions.find((d) => d.name === 'Accessibility');
+    const namingDim = result.dimensions.find((d) => d.name === 'Naming Consistency');
+
+    const docBase = DIMENSION_REGISTRY.find((d) => d.name === 'CEM Completeness')!.weight;
+    const a11yBase = DIMENSION_REGISTRY.find((d) => d.name === 'Accessibility')!.weight;
+    const namingBase = DIMENSION_REGISTRY.find((d) => d.name === 'Naming Consistency')!.weight;
+
+    expect(docDim!.weight).toBeCloseTo(docBase * 2.0);
+    expect(a11yDim!.weight).toBeCloseTo(a11yBase * 0.5);
+    expect(namingDim!.weight).toBeCloseTo(namingBase * 3.0);
+  });
+});
+
+// ─── Config loading — scoring.weights from helixir.mcp.json ──────────────────
+
+describe('loadConfig — scoring.weights', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    vi.unstubAllEnvs();
+    tmpDir = mkdtempSync(join(tmpdir(), 'helixir-scoring-test-'));
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('scoring defaults to undefined when not in config file', () => {
+    writeFileSync(join(tmpDir, 'helixir.mcp.json'), JSON.stringify({ cemPath: 'cem.json' }));
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const config = loadConfig();
+
+    expect(config.scoring).toBeUndefined();
+  });
+
+  it('loads scoring.weights from helixir.mcp.json', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({
+        cemPath: 'cem.json',
+        scoring: {
+          weights: {
+            accessibility: 1.5,
+            documentation: 2.0,
+          },
+        },
+      }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const config = loadConfig();
+
+    expect(config.scoring?.weights?.accessibility).toBe(1.5);
+    expect(config.scoring?.weights?.documentation).toBe(2.0);
+  });
+
+  it('loads scoring.weights with all supported keys', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({
+        scoring: {
+          weights: {
+            documentation: 1.0,
+            accessibility: 1.5,
+            typeCoverage: 1.0,
+            apiConsistency: 1.0,
+            cssArchitecture: 0.5,
+            eventArchitecture: 1.0,
+            testCoverage: 2.0,
+            bundleSize: 0.5,
+            storyCoverage: 0.5,
+            performance: 0.5,
+            drupalReadiness: 0.5,
+            cemSourceFidelity: 0.5,
+            slotArchitecture: 1.0,
+            naming: 1.0,
+          },
+        },
+      }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const config = loadConfig();
+
+    expect(config.scoring?.weights?.documentation).toBe(1.0);
+    expect(config.scoring?.weights?.accessibility).toBe(1.5);
+    expect(config.scoring?.weights?.typeCoverage).toBe(1.0);
+    expect(config.scoring?.weights?.apiConsistency).toBe(1.0);
+    expect(config.scoring?.weights?.cssArchitecture).toBe(0.5);
+    expect(config.scoring?.weights?.eventArchitecture).toBe(1.0);
+    expect(config.scoring?.weights?.testCoverage).toBe(2.0);
+    expect(config.scoring?.weights?.bundleSize).toBe(0.5);
+    expect(config.scoring?.weights?.storyCoverage).toBe(0.5);
+    expect(config.scoring?.weights?.performance).toBe(0.5);
+    expect(config.scoring?.weights?.drupalReadiness).toBe(0.5);
+    expect(config.scoring?.weights?.cemSourceFidelity).toBe(0.5);
+    expect(config.scoring?.weights?.slotArchitecture).toBe(1.0);
+    expect(config.scoring?.weights?.naming).toBe(1.0);
+  });
+
+  it('rejects non-positive weights (zero) with a warning', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({
+        scoring: { weights: { accessibility: 0 } },
+      }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      const config = loadConfig();
+      // Zero is invalid — should be discarded
+      expect(config.scoring?.weights?.accessibility).toBeUndefined();
+      expect(stderrSpy).toHaveBeenCalledWith(
+        expect.stringContaining('scoring.weights.accessibility'),
+      );
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+
+  it('rejects negative weights with a warning', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({
+        scoring: { weights: { documentation: -1 } },
+      }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      const config = loadConfig();
+      expect(config.scoring?.weights?.documentation).toBeUndefined();
+      expect(stderrSpy).toHaveBeenCalledWith(
+        expect.stringContaining('scoring.weights.documentation'),
+      );
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+
+  it('rejects non-numeric weights with a warning', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({
+        scoring: { weights: { accessibility: 'high' } },
+      }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      const config = loadConfig();
+      expect(config.scoring?.weights?.accessibility).toBeUndefined();
+      expect(stderrSpy).toHaveBeenCalledWith(
+        expect.stringContaining('scoring.weights.accessibility'),
+      );
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+
+  it('accepts valid weights alongside invalid ones, discarding only invalid', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({
+        scoring: {
+          weights: {
+            accessibility: 2.0, // valid
+            documentation: -1, // invalid — negative
+          },
+        },
+      }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      const config = loadConfig();
+      expect(config.scoring?.weights?.accessibility).toBe(2.0);
+      expect(config.scoring?.weights?.documentation).toBeUndefined();
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+
+  it('scoring.weights absent from config leaves scoring undefined', () => {
+    writeFileSync(
+      join(tmpDir, 'helixir.mcp.json'),
+      JSON.stringify({ scoring: {} }),
+    );
+    vi.stubEnv('MCP_WC_PROJECT_ROOT', tmpDir);
+
+    const config = loadConfig();
+
+    // scoring present but weights absent — either undefined scoring or empty weights
+    expect(config.scoring?.weights).toBeUndefined();
+  });
+});