@avi770/testteam 2.0.0 → 3.2.0

package/dist/core/ui-ux/orchestrator.js

@@ -0,0 +1,672 @@
+/**
+ * UI/UX Design Sub-Orchestrator (Agent #15 — "The Designer").
+ *
+ * Coordinates the design toolchain: composes engine agents (#8/#67 a11y,
+ * #12 UX Inspector, #29 Responsive, #80 Usability), enforces brand rules,
+ * gates on visual diff (skip unchanged screens), validates design-system
+ * conformance, generates mockup alternatives, and emits A/B hypotheses to
+ * Experiment Runner (#6). Reports a `DesignAuditReport` up to Master
+ * Orchestrator (#26) and a `DesignQualitySignal` to Quality Score (#14).
+ *
+ * Hard rules (enforced here, not just advisory):
+ *   1. A11y violations are BLOCKING — uxScore = 0 and a11yGatePassed = false.
+ *   2. UI changes are NEVER auto-shipped — mockups carry `requiresHumanApproval: true`.
+ *   3. Unchanged screens are SKIPPED (visual-diff gate, improvement #1).
+ *   4. Off-design-system values are FLAGGED (improvement #2).
+ *   5. Every suggestion becomes a testable hypothesis for #6 (improvement #10).
+ *
+ * Pure functions are exported separately so tests can exercise them directly
+ * without constructing the full orchestrator.
+ *
+ * Spec: blueprint/agents/15-ui-ux-design.md
+ */
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+const DEFAULT_MOTION_BUDGET_MS = 300;
+const DEFAULT_MIN_MOCKUPS = 2;
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
+/**
+ * Visual-diff gate (improvement #1).
+ *
+ * Compares the current content hash to the previous snapshot.
+ * Returns `skipped: true` iff the hash is unchanged.
+ * New screens (no previous snapshot) are NOT skipped.
+ */
+export function evaluateDiffGate(current, previous) {
+    if (previous === null) {
+        return {
+            screenId: current.screenId,
+            skipped: false,
+            previousHash: null,
+            currentHash: current.contentHash,
+            reason: 'new-screen',
+        };
+    }
+    const unchanged = previous.contentHash === current.contentHash;
+    return {
+        screenId: current.screenId,
+        skipped: unchanged,
+        previousHash: previous.contentHash,
+        currentHash: current.contentHash,
+        reason: unchanged ? 'unchanged' : 'hash-changed',
+    };
+}
+/**
+ * Map severity strings from engine agents to `IssueSeverity`.
+ *
+ * Fail-CLOSED on unknown input: a malformed/unrecognised severity (e.g. a
+ * typo'd 'critcal', or an empty string) is treated conservatively as 'high'
+ * rather than 'info'. Mapping garbage to 'info' would grant it the 0-point
+ * "free pass" deduction in usability/responsive scoring and silently
+ * under-report a finding that may in fact be critical. The five known values
+ * (including 'info') map to themselves.
+ */
+export function mapSeverity(raw) {
+    switch (raw) {
+        case 'critical': return 'critical';
+        case 'high': return 'high';
+        case 'medium': return 'medium';
+        case 'low': return 'low';
+        case 'info': return 'info';
+        default: return 'high';
+    }
+}
+/** Valid responsive breakpoints — whitelist for fail-closed validation. */
+const VALID_BREAKPOINTS = new Set([
+    'mobile',
+    'tablet',
+    'desktop',
+]);
+/**
+ * Validate an engine-provided breakpoint string against the known set.
+ *
+ * Unknown or absent values fall back to 'desktop' via a REAL membership check —
+ * not a blind `as Breakpoint` cast that would let an invalid runtime value
+ * (e.g. "widescreen") masquerade as a typed Breakpoint and flow downstream.
+ * The cast after the `.has()` guard is sound: the runtime check has already
+ * proven `raw` is one of the three valid breakpoints.
+ */
+export function toBreakpoint(raw) {
+    return raw !== undefined && VALID_BREAKPOINTS.has(raw)
+        ? raw
+        : 'desktop';
+}
+/**
+ * Convert axe-core-style impact strings to the `A11yViolation['impact']` enum.
+ * Unknown values default to 'minor' (never silently inflates to critical).
+ */
+export function mapAxeImpact(impact) {
+    switch (impact.toLowerCase()) {
+        case 'critical': return 'critical';
+        case 'serious': return 'serious';
+        case 'moderate': return 'moderate';
+        default: return 'minor';
+    }
+}
+/**
+ * Map a core `FindingSeverity` to the `A11yViolation['impact']` enum.
+ *
+ * `composeA11yViolations` receives `A11yEngineFinding`s whose `.severity` is a
+ * core `FindingSeverity` (`Pick<Finding, 'severity'>`) — NOT an axe-core impact
+ * string. Engine agents #8/#67 have already mapped axe impact → severity
+ * (agent #8: serious→high, moderate→medium, minor→low). This is the inverse of
+ * that map, so the axe→severity→impact round-trip preserves fidelity: a
+ * serious a11y finding (stored as severity 'high') surfaces as impact 'serious'
+ * rather than collapsing to 'minor'. Unknown → 'minor' (never inflates).
+ *
+ * (Historically the reader/orchestrator called `mapAxeImpact(f.severity)` here,
+ * which only recognises axe strings, so every non-'critical' severity — the
+ * common case — silently degraded to 'minor'. Only the dashboard's S6 posture
+ * view reads `.impact`, so this correction has no other consumer.)
+ */
+export function severityToImpact(severity) {
+    switch (severity.toLowerCase()) {
+        case 'critical': return 'critical';
+        case 'high': return 'serious';
+        case 'medium': return 'moderate';
+        case 'low': return 'minor';
+        case 'info': return 'minor';
+        default: return 'minor';
+    }
+}
+/**
+ * Compose engine-agent a11y findings into structured `A11yViolation[]`.
+ *
+ * ALL violations produced here carry `blocking: true` — the type system enforces
+ * this and callers cannot downgrade them (spec: "a11y is a hard floor").
+ */
+export function composeA11yViolations(engineOutput, screenId) {
+    return engineOutput.findings.map((f) => {
+        // Extract axe rule id from the finding id where possible.
+        // Engine agents encode it as "<agentId>-axe-<module>-<ruleId>".
+        const parts = f.id.split('-');
+        const ruleId = parts.length >= 4 ? parts.slice(3).join('-') : f.id;
+        const violation = {
+            ruleId,
+            description: f.description,
+            impact: severityToImpact(f.severity),
+            nodes: [screenId],
+            helpUrl: f.suggestedFix ?? `https://dequeuniversity.com/rules/axe/${ruleId}`,
+            blocking: true, // STRUCTURAL — cannot be set to false by callers
+        };
+        return violation;
+    });
+}
+/**
+ * Check a computed style map against the token registry (improvement #2).
+ *
+ * `computedStyles` is a map of `cssProperty -> computedValue` for one screen.
+ * Values not present in the registry are returned as `OffSystemValue` entries.
+ *
+ * Must-Fix #6: The `nearestToken` field reports the FIRST color token found in
+ * the registry when the off-system value is a hex color — it is NOT a
+ * color-distance-based nearest match. The field is preserved for callers that
+ * display a "did you mean?" hint; its approximate nature is documented here.
+ * A full chroma-distance implementation is a phase-2 enhancement.
+ */
+export function checkTokenConformance(screenId, computedStyles, tokenRegistry) {
+    const registeredValues = new Set(tokenRegistry.map((t) => t.value.toLowerCase()));
+    const offSystem = [];
+    for (const [prop, value] of computedStyles) {
+        const normalised = value.trim().toLowerCase();
+        if (!registeredValues.has(normalised)) {
+            // Return the first color token as a hint when the off-system value is a hex color.
+            // This is a registry-order hint, not a chroma-distance nearest-match.
+            const firstColorToken = normalised.startsWith('#')
+                ? tokenRegistry.find((t) => t.category === 'color')?.name
+                : undefined;
+            offSystem.push({
+                cssProperty: prop,
+                computedValue: value,
+                nearestToken: firstColorToken,
+                element: screenId,
+            });
+        }
+    }
+    return {
+        screenId,
+        offSystemValues: offSystem,
+        conformant: offSystem.length === 0,
+        // Real denominator for the brand-conformance ratio: how many declarations
+        // were actually inspected. 0 here => "no brand data" (scored N/A downstream,
+        // never a free perfect pass).
+        checkedCount: computedStyles.size,
+    };
+}
+/**
+ * Compute the usability score for one screen (improvement #5).
+ *
+ * Derives a 0..100 score from UX engine findings mapped to Nielsen heuristics,
+ * fused with Watcher friction points (improvement #6 — real-user grounded).
+ * Score is truncated (never rounded up) per Avi's QA standard.
+ *
+ * Math: each heuristic violation deducts points based on severity:
+ *   critical -20, high -10, medium -5, low -2
+ * Watcher friction deduction: frictionPoints.length * 2  (applied ONCE, outside the loop)
+ * Cognitive load = violations.length + friction (clamped 0..10).
+ *
+ * Must-Fix #2: Watcher friction deduction is applied ONCE per screen (outside
+ * the findings loop). The previous implementation applied it inside the loop,
+ * causing it to accumulate N*friction for N findings — inflating deductions by
+ * 2× per additional finding. An empty findings list would also silently ignore
+ * friction entirely.
+ */
+export function computeUsabilityScore(screenId, uxOutput, watcherFrictionPoints) {
+    const heuristicMap = {
+        'error-boundary': 'help-users-recover',
+        'loading-stuck': 'visibility-of-system-status',
+        'empty-state': 'recognition-over-recall',
+        'form-validation': 'error-prevention',
+        'truncated-text': 'aesthetic-minimalist',
+    };
+    const violations = [];
+    let deduction = 0;
+    for (const f of uxOutput.findings) {
+        const severity = mapSeverity(f.severity);
+        // Heuristic inference from finding id keyword
+        let heuristic = 'help-documentation';
+        for (const [keyword, h] of Object.entries(heuristicMap)) {
+            if (f.id.includes(keyword)) {
+                heuristic = h;
+                break;
+            }
+        }
+        const severityDeduction = severity === 'critical' ? 20 :
+            severity === 'high' ? 10 :
+                severity === 'medium' ? 5 :
+                    severity === 'low' ? 2 :
+                        0;
+        deduction += severityDeduction;
+        violations.push({ heuristic, description: f.description, severity });
+    }
+    // Must-Fix #2: Watcher friction deduction is applied ONCE per screen,
+    // outside the per-finding loop, so it does not compound with finding count.
+    deduction += watcherFrictionPoints.length * 2;
+    // Clamp base score to [0, 100], truncate (never round up)
+    const rawScore = Math.max(0, 100 - deduction);
+    const score = Math.trunc(rawScore * 100) / 100; // truncate to 2 dp
+    // Cognitive load: 1 per violation + 1 per friction point, clamped 0..10
+    const cognitiveLoad = Math.min(10, violations.length + watcherFrictionPoints.length);
+    return {
+        screenId,
+        score,
+        cognitiveLoad,
+        violations,
+        watcherFrictionPoints: [...watcherFrictionPoints],
+    };
+}
+/**
+ * Compose responsive engine output into structured `ResponsiveResult` (improvement #9).
+ */
+export function composeResponsiveResult(screenId, engineOutput) {
+    const issues = engineOutput.findings.map((f) => {
+        const bp = toBreakpoint(f.breakpoint);
+        return {
+            breakpoint: bp,
+            description: f.description,
+            severity: mapSeverity(f.severity),
+        };
+    });
+    return {
+        screenId,
+        issues,
+        passed: issues.filter((i) => i.severity === 'critical' || i.severity === 'high').length === 0,
+    };
+}
+/** Severity ordering for ranked output (0 = highest priority). */
+const SEVERITY_RANK = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};
+/**
+ * Build visual design issues from brand conformance check.
+ *
+ * Checks each `OffSystemValue` against `BrandGuidelines` and emits a
+ * `VisualDesignIssue` per violation. The color/font/spacing checks are
+ * deterministic against the provided guidelines (improvement #3 — brand memory).
+ *
+ * Output is RANKED by severity (critical → info) so the most important fixes
+ * surface first regardless of input order — the spec's "ranked fixes" rule is
+ * enforced here, not left to caller input order.
+ */
+export function buildBrandConformanceIssues(offSystemValues, brandGuidelines) {
+    const issues = [];
+    for (const osv of offSystemValues) {
+        const prop = osv.cssProperty.toLowerCase();
+        let category = 'consistency';
+        let detected = false;
+        if (prop === 'color' || prop === 'background-color' || prop === 'border-color') {
+            const normalised = osv.computedValue.toLowerCase();
+            if (!brandGuidelines.allowedColors.includes(normalised)) {
+                category = 'brand-adherence';
+                detected = true;
+            }
+        }
+        else if (prop === 'font-family') {
+            // Match the PRIMARY font in the stack as a WHOLE token (case-insensitive),
+            // NOT a substring — otherwise an off-brand "MyInterFont" would pass merely
+            // by containing an allowed "Inter". Strip quotes and take the first family.
+            const primaryFont = osv.computedValue
+                .split(',')[0]
+                .trim()
+                .replace(/^["']|["']$/g, '')
+                .toLowerCase();
+            const onBrand = brandGuidelines.allowedFonts.some((f) => f.toLowerCase() === primaryFont);
+            if (!onBrand) {
+                category = 'typography';
+                detected = true;
+            }
+        }
+        else if (prop === 'margin' || prop === 'padding' || prop === 'gap') {
+            // Check against spacing scale (px values as strings like "16px").
+            const pxMatch = osv.computedValue.match(/^(\d+(?:\.\d+)?)px$/);
+            if (pxMatch !== null) {
+                const pxVal = parseFloat(pxMatch[1]);
+                if (!brandGuidelines.spacingScale.includes(pxVal)) {
+                    category = 'spacing';
+                    detected = true;
+                }
+            }
+            else if (/\d/.test(osv.computedValue)) {
+                // A NUMERIC spacing value in a non-px unit (rem/em/%/vh/…) that is already
+                // off-registry. We cannot verify it against the px spacing scale, so we
+                // fail CLOSED and flag it rather than let an off-brand spacing value escape
+                // silently. Bare keywords (auto/inherit) contain no digit and are skipped.
+                category = 'spacing';
+                detected = true;
+            }
+        }
+        if (detected) {
+            issues.push({
+                category,
+                description: `Off-brand value "${osv.computedValue}" on property "${osv.cssProperty}" (element: ${osv.element})`,
+                suggestedFix: osv.nearestToken !== undefined
+                    ? `Replace with design token "${osv.nearestToken}"`
+                    : `Use a value from the brand ${category} scale`,
+                severity: category === 'brand-adherence' ? 'high' : 'medium',
+                element: osv.element,
+            });
+        }
+    }
+    // Rank by severity (critical first) so the highest-priority fixes lead.
+    issues.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
+    return issues;
+}
+/**
+ * Generate mockup alternative stubs for a flagged screen (improvement #4).
+ *
+ * In production the orchestrator would invoke Figma MCP / Canva / image-gen here.
+ * This layer returns deterministic stubs with `requiresHumanApproval: true` so the
+ * type system enforces the "never auto-ships UI" contract.
+ *
+ * `count` must be at least 2 (spec requirement). Callers should pass
+ * `config.minMockupAlternatives ?? 2`.
+ */
+export function generateMockupAlternatives(screenId, issueDescriptions, source, count, now) {
+    const safeCount = Math.max(2, count);
+    const ts = new Date(now()).toISOString();
+    return Array.from({ length: safeCount }, (_, i) => {
+        const id = `${screenId}-alt-${i + 1}`;
+        const rationale = issueDescriptions[i] !== undefined
+            ? `Alternative ${i + 1}: addresses "${issueDescriptions[i]}"`
+            : `Alternative ${i + 1}: improved visual hierarchy and spacing`;
+        const alt = {
+            id,
+            screenId,
+            rationale,
+            source,
+            assetUrl: `design://mockup/${screenId}/${id}?ts=${ts}`,
+            approvalStatus: null, // pending human decision
+            requiresHumanApproval: true, // STRUCTURAL — cannot be set to false
+        };
+        return alt;
+    });
+}
+/**
+ * Emit an Experiment Runner (#6) hypothesis from an accepted mockup (improvement #10).
+ *
+ * Every suggestion is a testable A/B hypothesis. The orchestrator emits one per
+ * accepted mockup alternative; #6 owns the experiment lifecycle from here.
+ */
+export function emitExperimentHypothesis(mockup, expectedImpact, now) {
+    return {
+        id: `hyp-${mockup.id}-${now()}`,
+        screenId: mockup.screenId,
+        change: mockup.rationale,
+        expectedImpact,
+        emittedAt: new Date(now()).toISOString(),
+        mockupId: mockup.id,
+    };
+}
+/**
+ * Compute the design quality signal for #14 (improvement #2 / #7).
+ *
+ * Sub-scores:
+ *   a11y: 0 if any violation, else 1 (hard floor — improvement #7)
+ *   visual: 1 - (criticalIssues * 0.25 + highIssues * 0.10)  clamped [0,1]
+ *   usability: uxScore.score / 100
+ *   responsive: 1 - (failedScreenRatio)
+ *   brandConformance: 1 - (offSystemCount / declarationsChecked), or N/A (null)
+ *                     when nothing was checked
+ *
+ * Overall uxScore = mean of the sub-scores that were actually MEASURED (brand
+ * conformance only participates when there was brand data), then clamped to 0
+ * when any a11y violation exists (a11y = hard floor). Truncated, never rounded up.
+ */
+export function computeDesignQualitySignal(componentId, a11yViolations, visualIssues, usabilityScore, responsiveResults, tokenConformanceResults, scoredAt) {
+    function trunc2(n) {
+        return Math.trunc(n * 100) / 100;
+    }
+    function clamp01(n) {
+        return Math.max(0, Math.min(1, n));
+    }
+    const a11yScore = a11yViolations.length === 0 ? 1 : 0;
+    const criticalVisual = visualIssues.filter((i) => i.severity === 'critical').length;
+    const highVisual = visualIssues.filter((i) => i.severity === 'high').length;
+    const visualScore = clamp01(1 - (criticalVisual * 0.25 + highVisual * 0.10));
+    const usabilityNorm = clamp01(usabilityScore / 100);
+    const totalResponsive = responsiveResults.length;
+    const failedResponsive = responsiveResults.filter((r) => !r.passed).length;
+    const responsiveScore = totalResponsive > 0
+        ? clamp01(1 - failedResponsive / totalResponsive)
+        : 1;
+    // Honest brand-conformance ratio: off-system declarations as a fraction of the
+    // TOTAL declarations actually checked (checkedCount). This replaces the old
+    // `1 - offSystemTotal / (offSystemTotal + numResults)` fudge whose +1-per-result
+    // denominator could never reach 0 and structurally softened bad brand scores.
+    //
+    // Fail-CLOSED on missing data: when nothing was checked (totalChecked === 0 —
+    // e.g. no computed styles were supplied) brandConformance is N/A (null) and is
+    // EXCLUDED from the mean. It is NOT scored as a perfect 1; absent evidence must
+    // never read as a pass.
+    const totalChecked = tokenConformanceResults.reduce((acc, r) => acc + r.checkedCount, 0);
+    const offSystemTotal = tokenConformanceResults.reduce((acc, r) => acc + r.offSystemValues.length, 0);
+    const brandScore = totalChecked > 0
+        ? clamp01(1 - offSystemTotal / totalChecked)
+        : null;
+    // Mean over the sub-scores that were actually measured. Brand conformance only
+    // participates when there was brand data to measure (null => omitted).
+    const measuredSubScores = [a11yScore, visualScore, usabilityNorm, responsiveScore];
+    if (brandScore !== null) {
+        measuredSubScores.push(brandScore);
+    }
+    const rawMean = measuredSubScores.reduce((acc, n) => acc + n, 0) / measuredSubScores.length;
+    // A11y hard floor: if any violation, uxScore = 0 regardless of other sub-scores.
+    const uxScore = a11yViolations.length > 0 ? 0 : trunc2(rawMean);
+    return {
+        componentId,
+        uxScore,
+        breakdown: {
+            visualDesign: trunc2(visualScore),
+            usability: trunc2(usabilityNorm),
+            a11y: a11yScore,
+            responsive: trunc2(responsiveScore),
+            brandConformance: brandScore === null ? null : trunc2(brandScore),
+        },
+        scoredAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// DesignOrchestrator — stateful, event-driven sub-orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Design sub-orchestrator for Agent #15.
+ *
+ * Maintains a snapshot cache for visual-diff gating (improvement #1).
+ * All mutation methods are pure-functional over their inputs; side-effects
+ * (tool invocations, MCP calls) are expected to happen at the *caller* level
+ * (the run engine), keeping this class deterministic and testable.
+ *
+ * Usage pattern:
+ *   const orchestrator = new DesignOrchestrator(config);
+ *   const report = orchestrator.audit(runId, screens, a11yOut, uxOut, responsiveOut);
+ *   // Report is immutable; caller routes to Dashboard, #14, #26.
+ */
+export class DesignOrchestrator {
+    config;
+    /** Snapshot cache: screenId → last known hash. Visual-diff gate (improvement #1). */
+    snapshotCache = new Map();
+    constructor(config = {}) {
+        this.config = {
+            brandGuidelines: config.brandGuidelines,
+            tokenRegistry: config.tokenRegistry ?? [],
+            motionBudgetMs: config.motionBudgetMs ?? DEFAULT_MOTION_BUDGET_MS,
+            minMockupAlternatives: Math.max(2, config.minMockupAlternatives ?? DEFAULT_MIN_MOCKUPS),
+            clock: config.clock ?? (() => Date.now()),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Snapshot cache management (visual-diff gate)
+    // -------------------------------------------------------------------------
+    /** Update the cached snapshot for a screen (called after each audit). */
+    updateSnapshot(snapshot) {
+        this.snapshotCache.set(snapshot.screenId, snapshot);
+    }
+    /** Return the cached snapshot for a screen, or null if unseen. */
+    getSnapshot(screenId) {
+        return this.snapshotCache.get(screenId) ?? null;
+    }
+    // -------------------------------------------------------------------------
+    // Core audit pipeline
+    // -------------------------------------------------------------------------
+    /**
+     * Run a full design audit for one pipeline pass.
+     *
+     * @param runId        - Unique identifier for this pipeline run.
+     * @param screens      - Current screen snapshots (hash = current state).
+     * @param a11yOutput   - Composed output from engine agents #8 / #67.
+     * @param uxOutput     - Composed output from engine agents #12 / #80.
+     * @param responsiveOutput - Composed output from engine agent #29.
+     * @param watcherFriction  - Real-user friction points from Watcher (#2), keyed
+     *                           PER SCREEN (`screenId -> friction descriptions`).
+     *                           A flat global list is wrong: friction recorded on
+     *                           one screen must not penalize every other screen's
+     *                           usability score.
+     * @param computedStyles   - Per-screen CSS computed-style map for token check.
+     * @param motionReviews    - Optional motion/animation reviews (phase-2).
+     *
+     * Returns a fully-immutable `DesignAuditReport`. Never auto-ships anything.
+     */
+    audit(runId, screens, a11yOutput, uxOutput, responsiveOutput, watcherFriction = new Map(), computedStyles = new Map(), motionReviews = []) {
+        const now = this.config.clock;
+        const auditedAt = new Date(now()).toISOString();
+        // --- Step 1: Visual-diff gate (improvement #1) ---
+        const diffGateResults = [];
+        const skippedScreens = [];
+        const auditedScreenIds = [];
+        for (const screen of screens) {
+            const previous = this.getSnapshot(screen.screenId);
+            const gateResult = evaluateDiffGate(screen, previous);
+            diffGateResults.push(gateResult);
+            if (gateResult.skipped) {
+                skippedScreens.push(screen.screenId);
+            }
+            else {
+                auditedScreenIds.push(screen.screenId);
+                // Update snapshot cache for next run
+                this.updateSnapshot(screen);
+            }
+        }
+        // --- Step 2: A11y violations (hard floor — improvement #7) ---
+        // Must-Fix #4: filter strictly on f.module === screenId. Removed the
+        // `|| auditedScreenIds.length <= 1` shortcut and the first-screen fallback
+        // that was dumping all a11y findings onto screen[0] in multi-screen runs.
+        // Each finding is attributed only to the screen whose id matches f.module.
+        // Findings whose module does not match any audited screen are silently
+        // dropped (they belong to a skipped or unknown screen).
+        const allA11yViolations = [];
+        for (const screenId of auditedScreenIds) {
+            const screenFindings = {
+                findings: a11yOutput.findings.filter((f) => f.module === screenId),
+            };
+            allA11yViolations.push(...composeA11yViolations(screenFindings, screenId));
+        }
+        // --- Step 3: Token conformance (improvement #2) ---
+        const tokenConformance = [];
+        for (const screenId of auditedScreenIds) {
+            const styles = computedStyles.get(screenId) ?? new Map();
+            tokenConformance.push(checkTokenConformance(screenId, styles, this.config.tokenRegistry));
+        }
+        // --- Step 4: Visual design issues (brand conformance — improvement #3) ---
+        const allOffSystem = tokenConformance.flatMap((r) => r.offSystemValues);
+        const visualDesignIssues = this.config.brandGuidelines
+            ? [...buildBrandConformanceIssues(allOffSystem, this.config.brandGuidelines)]
+            : allOffSystem.map((osv) => ({
+                category: 'consistency',
+                description: `Off-system value "${osv.computedValue}" on "${osv.cssProperty}"`,
+                suggestedFix: osv.nearestToken
+                    ? `Use token "${osv.nearestToken}"`
+                    : 'Replace with a registered design token',
+                severity: 'medium',
+                element: osv.element,
+            }));
+        // --- Step 5: Usability scores (improvement #5 + #6) ---
+        // Must-Fix #4: filter strictly on f.module === screenId (no length<=1 shortcut).
+        // BLOCKER fix: friction is attributed PER SCREEN — a friction point recorded
+        // on one screen must NOT deduct from every other screen's usability score.
+        const usabilityScores = [];
+        for (const screenId of auditedScreenIds) {
+            const screenUxOutput = {
+                findings: uxOutput.findings.filter((f) => f.module === screenId),
+            };
+            const screenFriction = watcherFriction.get(screenId) ?? [];
+            usabilityScores.push(computeUsabilityScore(screenId, screenUxOutput, screenFriction));
+        }
+        // --- Step 6: Responsive results (improvement #9) ---
+        // Must-Fix #4: filter strictly on f.module === sid (no length<=1 shortcut).
+        const responsiveResults = auditedScreenIds.map((sid) => {
+            const filtered = {
+                findings: responsiveOutput.findings.filter((f) => f.module === sid),
+            };
+            return composeResponsiveResult(sid, filtered);
+        });
+        // --- Step 7: Mockup alternatives (improvement #4 — ≥2 per flagged screen) ---
+        // A screen is flagged on its OWN issues only. The visual-issue test is
+        // per-screen (`i.element === sid`), not the aggregate `visualDesignIssues
+        // .length > 0` — otherwise a single off-brand value on one screen would flag
+        // (and generate mockups for) every audited screen.
+        const mockupAlternatives = [];
+        const flaggedScreens = auditedScreenIds.filter((sid) => allA11yViolations.some((v) => v.nodes.includes(sid)) ||
+            visualDesignIssues.some((i) => i.element === sid) ||
+            (usabilityScores.find((u) => u.screenId === sid)?.score ?? 100) < 70);
+        for (const screenId of flaggedScreens) {
+            // Mockup rationales reference THIS screen's own issues, not a global pool.
+            const descriptions = [
+                ...visualDesignIssues
+                    .filter((i) => i.element === screenId)
+                    .slice(0, 3)
+                    .map((i) => i.description),
+                ...allA11yViolations
+                    .filter((v) => v.nodes.includes(screenId))
+                    .slice(0, 3)
+                    .map((v) => v.description),
+            ];
+            mockupAlternatives.push(...generateMockupAlternatives(screenId, descriptions, 'figma', this.config.minMockupAlternatives, now));
+        }
+        // --- Step 8: Experiment hypotheses (improvement #10) ---
+        const experimentHypotheses = [];
+        for (const mockup of mockupAlternatives) {
+            experimentHypotheses.push(emitExperimentHypothesis(mockup, `Improve usability score and reduce a11y violations on "${mockup.screenId}"`, now));
+        }
+        // --- Step 9: Design quality signals (feeds #14) ---
+        const meanUsabilityScore = usabilityScores.length > 0
+            ? usabilityScores.reduce((acc, u) => acc + u.score, 0) / usabilityScores.length
+            : 100;
+        const qualitySignals = auditedScreenIds.map((sid) => {
+            const usScore = usabilityScores.find((u) => u.screenId === sid)?.score
+                ?? meanUsabilityScore;
+            // BLOCKER fix: attribute a11y + visual issues PER SCREEN. Passing the
+            // aggregate arrays here let ONE screen's a11y violation (the hard floor)
+            // zero EVERY screen's uxScore, and one screen's visual issue depress all
+            // the others. Each signal now sees only its own screen's issues.
+            const screenA11y = allA11yViolations.filter((v) => v.nodes.includes(sid));
+            const screenVisual = visualDesignIssues.filter((i) => i.element === sid);
+            return computeDesignQualitySignal(sid, screenA11y, screenVisual, usScore, responsiveResults.filter((r) => r.screenId === sid), tokenConformance.filter((r) => r.screenId === sid), auditedAt);
+        });
+        // --- A11y gate (improvement #7 — blocks the report) ---
+        const a11yGatePassed = allA11yViolations.length === 0;
+        return {
+            runId,
+            auditedAt,
+            skippedScreens,
+            diffGateResults,
+            a11yViolations: allA11yViolations,
+            visualDesignIssues,
+            tokenConformance,
+            usabilityScores,
+            responsiveResults,
+            motionReviews,
+            mockupAlternatives,
+            experimentHypotheses,
+            qualitySignals,
+            a11yGatePassed,
+        };
+    }
+}
+//# sourceMappingURL=orchestrator.js.map