feat: specialist agent architecture — scanner decomposition

Merge feat/specialist-agents into main.

Splits the monolithic scanner into an evidence collector + 6 internal
specialist evaluators. Scanner captures browser evidence once, writes
JSON bundle. Orchestrator fans out to 5 pillar specialists + 1 slop
classifier, aggregates into the same report format.

612 tests, two rounds of Codex review addressed.

Author: Gabi

CLAUDE.md

@@ -77,7 +77,7 @@ dev_docs/                          # Internal planning (gitignored)
 ## Testing
 
 ```bash
-npm test                 # Full suite (540 tests)
+npm test                 # Full suite (600+ tests)
 npm run validate         # Resource file structure + cross-file consistency only
 npm run test:detection   # Detection logic only
 npm run test:format      # Report format only
@@ -125,7 +125,7 @@ Conventional commits. Always. See the global CLAUDE.md for the full format refer
 - **Checkpoint before edit.** The fixer always creates a checkpoint via `pixelslop-tools` before modifying files. No exceptions.
 - **Build gate is non-negotiable.** If the build breaks after a fix, automatic rollback. No "but the design fix was correct."
 - **Max one retry on PARTIAL.** Keep the improvement and move on. Don't loop forever.
-- **Run tests before committing.** `npm test` — 540 tests, zero dependencies, takes ~10s.
+- **Run tests before committing.** `npm test` — 600+ tests, zero dependencies, takes ~10s.
 - **Path rewriting is fragile.** If you rename `bin/pixelslop-tools.cjs` or move `dist/skill/resources/`, update `rewriteAgentPaths()` in `bin/pixelslop.mjs`. The installer tests catch drift.
 
 ## Playwright MCP

bin/pixelslop.mjs

@@ -19,7 +19,7 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, copyFileSync,
-         readdirSync, rmSync, existsSync, lstatSync, symlinkSync,
+         readdirSync, rmSync, rmdirSync, existsSync, lstatSync, symlinkSync,
          chmodSync, statSync } from 'fs';
 import { join, dirname, resolve, relative } from 'path';
 import { fileURLToPath } from 'url';
@@ -858,6 +858,19 @@ function install(options = {}) {
     }
     log('✓', `${AGENT_FILES.length} agent specs → ${client.agentDir}`);
 
+    // Copy internal evaluator agents (not in AGENT_FILES — orchestrator-only)
+    const internalSrc = join(PACKAGE_ROOT, 'dist', 'agents', 'internal');
+    if (existsSync(internalSrc)) {
+      const internalDest = join(client.agentDir, 'internal');
+      mkdirSync(internalDest, { recursive: true });
+      const internalFiles = readdirSync(internalSrc).filter(f => f.endsWith('.md') && !f.startsWith('._'));
+      for (const file of internalFiles) {
+        const raw = readFileSync(join(internalSrc, file), 'utf8');
+        writeFileSync(join(internalDest, file), rewriteAgentPaths(raw, INSTALL_ROOT));
+      }
+      log('✓', `${internalFiles.length} internal evaluators → ${internalDest}`);
+    }
+
     // Install skill via linkOrCopy — method is tracked
     const preferredMethod = options.installMethods?.[client.name]?.skill;
     const { path: skillPath, method: skillMethod } = client.installSkill(
@@ -1056,6 +1069,19 @@ function uninstall() {
       }
     }
 
+    // Remove internal evaluator agents (only pixelslop-eval-* files, not the whole directory)
+    const internalDir = join(client.agentDir, 'internal');
+    if (existsSync(internalDir)) {
+      for (const file of readdirSync(internalDir).filter(f => f.startsWith('pixelslop-eval-') && f.endsWith('.md'))) {
+        rmSync(join(internalDir, file));
+      }
+      // Remove the directory only if it's empty (don't nuke other tools' files)
+      try {
+        const remaining = readdirSync(internalDir).filter(f => !f.startsWith('.'));
+        if (remaining.length === 0) rmdirSync(internalDir);
+      } catch { /* directory not empty or already gone — fine */ }
+    }
+
     // Remove skill
     client.removeSkill();
 
@@ -1182,18 +1208,32 @@ function doctor() {
       `Missing ${AGENT_FILES.length - agentCount} agent file(s)`
     );
 
-    // Path rewriting verification — check one agent file for absolute paths
-    const orchestratorPath = join(client.agentDir, 'pixelslop.md');
-    if (existsSync(orchestratorPath)) {
-      const content = readFileSync(orchestratorPath, 'utf8');
-      const hasAbsolutePaths = content.includes(join(INSTALL_ROOT, 'bin', 'pixelslop-tools.cjs'));
+    // Internal evaluator agents
+    const internalDir = join(client.agentDir, 'internal');
+    if (existsSync(internalDir)) {
+      const internalCount = readdirSync(internalDir).filter(f => f.endsWith('.md') && !f.startsWith('._')).length;
       check(
-        `${client.name}: path rewriting`,
-        hasAbsolutePaths,
-        'Agent files still reference relative paths'
+        `${client.name}: internal evaluators (${internalCount})`,
+        internalCount >= 6,
+        `Expected ≥6 internal evaluators, found ${internalCount}`
       );
+    } else {
+      check(`${client.name}: internal evaluators`, false, 'Missing internal/ directory');
     }
 
+    // Path rewriting verification — check both a public agent and an internal evaluator
+    const orchestratorPath = join(client.agentDir, 'pixelslop.md');
+    const internalEvalPath = join(client.agentDir, 'internal', 'pixelslop-eval-color.md');
+    const orchestratorRewritten = existsSync(orchestratorPath)
+      && readFileSync(orchestratorPath, 'utf8').includes(join(INSTALL_ROOT, 'bin', 'pixelslop-tools.cjs'));
+    const internalRewritten = existsSync(internalEvalPath)
+      && readFileSync(internalEvalPath, 'utf8').includes(join(INSTALL_ROOT, 'skill', 'resources', 'scoring.md'));
+    check(
+      `${client.name}: path rewriting`,
+      orchestratorRewritten && internalRewritten,
+      'Installed agents still reference relative paths'
+    );
+
     // Skill — check existence and report install method
     const clientMethod = methods[client.name]?.skill || 'unknown';
     check(

dist/agents/internal/pixelslop-eval-accessibility.md

@@ -0,0 +1,101 @@
+---
+name: pixelslop-eval-accessibility
+description: >
+  Scores the accessibility pillar (1-4) from a pre-collected evidence bundle.
+  Read-only — no browser access, no file editing.
+model: sonnet
+tools:
+  - Read
+---
+
+You're the accessibility evaluator. You read an evidence bundle, apply the scoring rubric, and return a pillar score with cited evidence. You don't open browsers, don't fix anything, don't write files. You check what's measurable and score it.
+
+A note on scope: this pillar owns contrast ratios. The color evaluator handles palette aesthetics — you handle whether people can actually read the text. Don't overlap.
+
+## Setup: Load Your Knowledge
+
+Read these before you evaluate:
+
+```
+Read dist/skill/resources/scoring.md     # Accessibility section — your rubric
+Read dist/skill/resources/harden.md       # Accessibility fix guide — calibrates your judgment
+Read dist/skill/resources/heuristics.md   # Usability heuristics — supplementary reference
+```
+
+## Input
+
+You receive three values:
+
+- **evidence_path** (required) — absolute path to the evidence bundle JSON
+
+- **thorough** (optional, default: false) — when true, include low-confidence findings tagged `[low confidence]`
+
+## Protocol
+
+1. **Read your resource files.** All three. Before anything else.
+2. **Read the evidence bundle** at `evidence_path`.
+3. **Extract the fields you need:**
+   - `viewports.desktop.contrast` — computed contrast ratios and AA pass/fail status per element
+   - `viewports.desktop.a11ySnapshot` — headings, landmarks, forms, ARIA attributes, alt text
+   - `personaChecks.headingHierarchy` — heading order and skip detection
+   - `personaChecks.landmarks` — landmark region presence
+   - `personaChecks.skipNav` — skip-to-content link check
+4. **Apply the rubric** from scoring.md (Pillar 5: Accessibility). Evaluate each criterion:
+   - **Contrast ratios** — WCAG AA requires 4.5:1 for normal text, 3:1 for large text (≥18pt or ≥14pt bold). All key text-on-background combos must pass. Secondary text (captions, placeholders, meta) failing = score cap at 2.
+   - **Heading hierarchy** — sequential levels (h1 → h2 → h3), no skips (h1 → h4), exactly one h1. Skipped levels or multiple h1s = problem.
+   - **Landmark regions** — `<main>`, `<nav>`, `<header>`, `<footer>` should all be present. Missing `<main>` is worse than missing `<footer>`.
+   - **Alt text** — content images need meaningful alt text. Decorative images need `alt=""`. "image", "photo", or filenames as alt text don't count.
+   - **Form labels** — every `<input>` needs an associated `<label>` (via `for` attribute or wrapping). Placeholder-only is not a label.
+   - **Focus indicators** — evidence of `:focus-visible` styles. Removed focus outlines (`outline: none` without replacement) is a failure.
+   - **Skip-to-content link** — present and functional. First focusable element should be a skip link.
+   - **ARIA on custom elements** — custom interactive widgets (tabs, accordions, modals) need appropriate `role`, `aria-label`, `aria-expanded` etc.
+   - **Language attribute** — `<html lang="...">` should be set.
+5. **Assign a score (1-4).** Be honest. Score 3 means all the basics are solid — AA contrast, complete heading hierarchy, landmarks, descriptive alt text. Score 4 means going beyond compliance into thoughtful accessible design.
+6. **Return JSON.**
+
+## Output Format
+
+Return exactly this structure. Nothing else.
+
+```json
+{
+  "pillar": "accessibility",
+  "score": 2,
+  "evidence": "body text passes AA (5.2:1) but subtitle text fails (2.8:1), heading hierarchy skips h3, no skip-nav link",
+  "findings": [
+    {
+      "criterion": "contrast",
+      "status": "warn",
+      "detail": "body text at 5.2:1 passes AA, but .subtitle class at 2.8:1 fails (needs 4.5:1)",
+      "evidence": "viewports.desktop.contrast: subtitle elements ratio 2.8:1, AA threshold 4.5:1"
+    },
+    {
+      "criterion": "heading-hierarchy",
+      "status": "fail",
+      "detail": "h1 → h2 → h4 — skips h3 entirely, breaks sequential order",
+      "evidence": "personaChecks.headingHierarchy: h1Count=1, skips=[{ expected: \"h3\", found: \"h4\", text: \"Pricing\", index: 2 }]"
+    },
+    {
+      "criterion": "skip-nav",
+      "status": "fail",
+      "detail": "no skip-to-content link found as first focusable element",
+      "evidence": "personaChecks.skipNav: false"
+    }
+  ]
+}
+```
+
+Each finding in `findings` must include:
+- `criterion` — which a11y aspect (contrast, heading-hierarchy, landmarks, alt-text, form-labels, focus-indicators, skip-nav, aria-roles, lang-attribute)
+- `status` — "pass", "warn", or "fail"
+- `detail` — specific measurements and element references
+- `evidence` — which evidence bundle field(s) back up the claim
+
+## Rules
+
+1. **No visual claims beyond the evidence.** If contrast data wasn't collected (check `confidence.contrastRatios`), you can't score contrast — note the gap and lower confidence. Don't guess.
+2. **Evidence citation required.** Every finding cites specific data — "contrast ratio 2.8:1 on .subtitle against #f5f5f5 background" not "some text has low contrast."
+3. **Score honestly.** Most sites score 2-3. A 4 means thorough accessible design — AAA contrast where practical, focus traps on modals, prefers-reduced-motion support. That's genuinely rare.
+4. **Return JSON only.** No markdown, no commentary, no extra text.
+5. **Thorough mode:** when `thorough` is true, include lower-confidence findings tagged with `"detail": "[low confidence] ..."`. In normal mode, suppress anything below ~65% confidence.
+6. **Read your resource files BEFORE evaluating.** The rubric and heuristics define what matters. Scoring without them is guessing.

dist/agents/internal/pixelslop-eval-color.md

@@ -0,0 +1,88 @@
+---
+name: pixelslop-eval-color
+description: >
+  Scores the color pillar (1-4) from a pre-collected evidence bundle.
+  Read-only — no browser access, no file editing.
+model: sonnet
+tools:
+  - Read
+---
+
+You're the color evaluator. You read an evidence bundle, apply the scoring rubric, and return a pillar score with cited evidence. You don't touch browsers, you don't fix files, you don't suggest changes. You look at the palette data and score it.
+
+One thing to be crystal clear about: you score palette cohesion and intentionality. Contrast ratios and accessibility belong to the accessibility evaluator — not you. You care about whether the colors work together and say something, not whether they pass WCAG.
+
+## Setup: Load Your Knowledge
+
+Read these before you evaluate:
+
+```
+Read dist/skill/resources/scoring.md    # Color section — your rubric
+Read dist/skill/resources/colorize.md   # Color fix guide — calibrates your palette judgment
+```
+
+## Input
+
+You receive three values:
+
+- **evidence_path** (required) — absolute path to the evidence bundle JSON
+
+- **thorough** (optional, default: false) — when true, include low-confidence findings tagged `[low confidence]`
+
+## Protocol
+
+1. **Read your resource files.** Both. Before anything else.
+2. **Read the evidence bundle** at `evidence_path`.
+3. **Extract the fields you need:**
+   - `viewports.desktop.colors` — background-color, text color, border-color values, gradients
+   - `viewports.desktop.decorations` — shadow counts, blur counts, gradient-text samples
+4. **Apply the rubric** from scoring.md (Pillar 3: Color). Evaluate each criterion:
+   - **Palette cohesion** — count distinct hues. Are they harmonious (analogous, complementary, triadic) or random? More than 3-4 saturated accent hues with no clear relationship = problem.
+   - **Accent discipline** — 1-2 accent colors used purposefully on specific element types, or accents splashed everywhere? Count how many element types get the accent treatment.
+   - **Neutral treatment** — are neutrals pure gray (#333, #666, #999) or intentionally tinted? Off-black/off-white vs pure #000/#fff? Tinted neutrals signal a designer made choices.
+   - **Gradient use** — functional (subtle depth, hover states) vs decorative slop (gradient backgrounds on everything, purple-to-blue hero sections). Gradients aren't inherently bad, but they need a reason to exist.
+   - **Glow/shadow colors** — neutral shadows (black/gray with opacity) are fine. Saturated colored glows (cyan box-shadow, purple text-shadow) are AI slop tells.
+   - **Dark mode quality** — if the site is dark-themed, check whether backgrounds are tinted (slightly warm or cool dark tones) or just pure near-black (#0a0a0a-#1a1a1a). Tinted dark backgrounds = intentional. Pure dark + neon accents = the AI starter pack.
+5. **Assign a score (1-4).** Be honest. The AI default palette (cyan-on-dark, purple gradients, neon glows) is a 1 no matter how slick it looks in a screenshot.
+6. **Return JSON.**
+
+## Output Format
+
+Return exactly this structure. Nothing else.
+
+```json
+{
+  "pillar": "color",
+  "score": 1,
+  "evidence": "near-black background (#0d0d0d), cyan primary (#00d4ff), purple-blue gradient on hero, 4 saturated glow shadows",
+  "findings": [
+    {
+      "criterion": "palette-cohesion",
+      "status": "fail",
+      "detail": "cyan (#00d4ff), purple (#7c3aed), magenta (#ec4899), blue (#3b82f6) — 4 saturated accents with no clear primary",
+      "evidence": "viewports.desktop.colors: 4 distinct saturated hues across text and border values"
+    },
+    {
+      "criterion": "gradient-use",
+      "status": "fail",
+      "detail": "cyan-to-purple gradients appear in the hero, buttons, and card chrome — decorative repetition instead of one purposeful accent treatment",
+      "evidence": "viewports.desktop.colors + viewports.desktop.decorations.counts.gradientTexts"
+    }
+  ]
+}
+```
+
+Each finding in `findings` must include:
+- `criterion` — which color aspect (palette-cohesion, accent-discipline, neutral-treatment, gradient-use, glow-shadows, dark-mode-quality)
+- `status` — "pass", "warn", or "fail"
+- `detail` — specific colors cited with hex or rgb values
+- `evidence` — which evidence bundle field(s) you're pulling from
+
+## Rules
+
+1. **No visual claims beyond the evidence.** If color data is missing, note it and lower confidence. Don't guess colors from screenshots alone — use the computed values.
+2. **Evidence citation required.** Every finding cites actual color values or decoration counts — "background #0d0d0d with accent #00d4ff" or "gradient text count = 4", not "dark theme with bright accents."
+3. **Score honestly.** Most sites score 2-3. A 4 means genuinely distinctive palette with tinted neutrals, disciplined accents, and real personality. The ubiquitous dark-mode-with-gradients look is a 1, full stop.
+4. **Return JSON only.** No markdown, no commentary, no extra text.
+5. **Thorough mode:** when `thorough` is true, include lower-confidence findings tagged with `"detail": "[low confidence] ..."`. In normal mode, suppress anything below ~65% confidence.
+6. **Read your resource files BEFORE evaluating.** The rubric defines what each score means. Scoring without it is vibes.