similarbuild 0.1.0

package/templates/skills/sb-inspect-live/scripts/tests/test-inspect-live.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// test-inspect-live.mjs — Smoke tests that don't require chromium.
+// Validates: --help works, missing args fail with exit code 2, syntax loads.
+// Browser-driven integration tests are deliberately out of scope here —
+// they belong in a separate harness that can pre-install playwright.
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { strict as assert } from 'node:assert'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(here, '..', 'inspect-live.mjs')
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+test('--help exits 0 and prints usage', () => {
+  const r = spawnSync('node', [SCRIPT, '--help'], { encoding: 'utf8' })
+  assert.equal(r.status, 0, `exit code was ${r.status}`)
+  assert.match(r.stdout, /inspect-live\.mjs/)
+  assert.match(r.stdout, /--url/)
+  assert.match(r.stdout, /--viewport-width/)
+  assert.match(r.stdout, /--output-dir/)
+  assert.match(r.stdout, /--selector/)
+  assert.match(r.stdout, /--wait-strategy/)
+})
+
+test('missing --url exits 2', () => {
+  const r = spawnSync('node', [SCRIPT, '--output-dir', '/tmp/sb-test'], { encoding: 'utf8' })
+  assert.equal(r.status, 2, `exit code was ${r.status}`)
+  assert.match(r.stderr, /missing --url/)
+})
+
+test('missing --output-dir exits 2', () => {
+  const r = spawnSync('node', [SCRIPT, '--url', 'https://example.com'], { encoding: 'utf8' })
+  assert.equal(r.status, 2, `exit code was ${r.status}`)
+  assert.match(r.stderr, /missing --output-dir/)
+})
+
+test('non-numeric viewport exits 2', () => {
+  const r = spawnSync(
+    'node',
+    [SCRIPT, '--url', 'https://example.com', '--output-dir', '/tmp/sb-test', '--viewport-width', 'foo'],
+    { encoding: 'utf8' },
+  )
+  assert.equal(r.status, 2, `exit code was ${r.status}`)
+  assert.match(r.stderr, /viewport must be numeric/)
+})
+
+// ─── Pattern #23 — widgetBlocked composite signal ──────────────────────────
+// The script's main() exits on missing args, so we mirror the regex tables
+// inline (same approach as test-validate-render.mjs uses for schema regex).
+
+const BLOCK_PATTERNS = [
+  /just a moment/i,
+  /checking your browser/i,
+  /enable javascript( and cookies)? to continue/i,
+  /cloudflare/i,
+  /access denied/i,
+  /verifying you are human/i,
+  /please complete the security check/i,
+  /captcha/i,
+  /forbidden/i,
+]
+const BLOCK_TITLE_PATTERNS = [
+  /just a moment/i,
+  /attention required/i,
+  /access denied/i,
+  /forbidden/i,
+  /captcha/i,
+]
+
+function blockedFor({ title = '', bodyText = '', bodyHtmlLen = 0, meaningfulChildren = 0 }) {
+  const blockedByBodyPattern = BLOCK_PATTERNS.some((re) => re.test(bodyText))
+  const blockedByTitlePattern = BLOCK_TITLE_PATTERNS.some((re) => re.test(title))
+  const extremeTiny = bodyHtmlLen < 256
+  const smallAndBare = bodyHtmlLen >= 256 && bodyHtmlLen < 1024 && meaningfulChildren < 2
+  return blockedByBodyPattern || blockedByTitlePattern || extremeTiny || smallAndBare
+}
+
+test('Pattern #23: example.com (528B body, 2+ meaningful children) → NOT blocked', () => {
+  // example.com renders a real page with <h1>, <p>, <a>; body innerText is
+  // benign prose. The OLD `bodyHtmlLen < 1024` heuristic falsely flagged it.
+  const r = blockedFor({
+    title: 'Example Domain',
+    bodyText: 'This domain is for use in illustrative examples in documents.',
+    bodyHtmlLen: 528,
+    meaningfulChildren: 2,
+  })
+  assert.equal(r, false, 'minimalist example.com should not be widget-blocked')
+})
+
+test('Pattern #23: info.cern.ch-class minimalist page (646B, 2+ children) → NOT blocked', () => {
+  const r = blockedFor({
+    title: 'World Wide Web',
+    bodyText: 'A look at the project that started it all.',
+    bodyHtmlLen: 646,
+    meaningfulChildren: 3,
+  })
+  assert.equal(r, false)
+})
+
+test('Pattern #23: extreme-tiny (< 256B) → blocked regardless of patterns', () => {
+  const r = blockedFor({ title: '', bodyText: '', bodyHtmlLen: 100, meaningfulChildren: 0 })
+  assert.equal(r, true)
+})
+
+test('Pattern #23: small AND bare (300B, 1 child) → blocked', () => {
+  const r = blockedFor({
+    title: 'Loading…',
+    bodyText: 'loading',
+    bodyHtmlLen: 300,
+    meaningfulChildren: 1,
+  })
+  assert.equal(r, true)
+})
+
+test('Pattern #23: Cloudflare title-only challenge → blocked', () => {
+  const r = blockedFor({
+    title: 'Just a moment...',
+    bodyText: '',
+    bodyHtmlLen: 1500,
+    meaningfulChildren: 3,
+  })
+  assert.equal(r, true)
+})
+
+test('Pattern #23: "Attention Required" Cloudflare title → blocked', () => {
+  const r = blockedFor({
+    title: 'Attention Required! | Cloudflare',
+    bodyText: 'Please complete the security check.',
+    bodyHtmlLen: 2000,
+    meaningfulChildren: 3,
+  })
+  assert.equal(r, true)
+})
+
+test('Pattern #23: body-text "checking your browser" → blocked', () => {
+  const r = blockedFor({
+    title: '',
+    bodyText: 'Checking your browser before accessing the site.',
+    bodyHtmlLen: 5000,
+    meaningfulChildren: 5,
+  })
+  assert.equal(r, true)
+})
+
+test('Pattern #23: large legitimate page (5K body, 10+ children, no patterns) → NOT blocked', () => {
+  const r = blockedFor({
+    title: 'My Online Store',
+    bodyText: 'Welcome to our shop. Featured products this week. Free shipping over $50.',
+    bodyHtmlLen: 50000,
+    meaningfulChildren: 25,
+  })
+  assert.equal(r, false)
+})
+
+test('Pattern #23: captcha keyword anywhere in body → blocked', () => {
+  const r = blockedFor({
+    title: '',
+    bodyText: 'Please solve the captcha to continue.',
+    bodyHtmlLen: 4000,
+    meaningfulChildren: 3,
+  })
+  assert.equal(r, true)
+})
+
+process.stdout.write(`\n${passed} passed, ${failed} failed\n`)
+process.exit(failed === 0 ? 0 : 1)

package/templates/skills/sb-review-checks/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: sb-review-checks
+description: Audits a built HTML/Liquid fragment against canonical visual anti-patterns, accessibility/performance/web-standards baselines, and (optionally) cross-references the violations with `sb-compare-visual` diffs to produce a prioritized list of specific candidate fixes for the auto-correct loop. Use when the SimilarBuild orchestrator (`/build-page`, `/build-site`, `/clip-section`) needs to audit a build before shipping or to generate `fixHints` for `sb-build-wp` / `sb-build-shopify`, or when the user asks to 'review checks' on a built fragment.
+---
+
+# sb-review-checks
+
+## Overview
+
+Closes the **build → validate → compare → review** cycle. Takes whatever `sb-build-wp` or `sb-build-shopify` produced, parses it (cheerio for HTML/Liquid, regex for CSS), and runs three independent groups of deterministic checks:
+
+1. **Anti-patterns** — the canon `#1, #2, #3, #4, #5, #5b, #6, #8` from the migration bootstrap (`#7` and `#9` are process-level, prevented by other skills).
+2. **Design quality** — the 12 a11y / performance / web-standards baselines that every production fragment must clear.
+3. **Cross-reference** — when `--compare-diffs` is supplied, violations whose location overlaps a high-severity visual diff are escalated and tagged.
+
+Pure determinism — no chromium, no network. The script does the work; this SKILL.md only describes inputs, outputs, and how to react to a non-zero exit.
+
+This skill is the **engine of the auto-correct loop**. Its `candidateFix` strings are the contract with `sb-build-{wp,shopify}`: specific enough to apply programmatically as `fixHints`, never generic ("improve specificity" is useless — "rewrite `.hero__title` as `.hero .hero__title`" is actionable). When you generate or hand-edit fix text, treat it as patch instructions, not prose.
+
+The split between **mechanical** (script) and **semantic** (LLM) is explicit: regex/AST decides whether `alt` is *present*; you decide whether it's *meaningful*. The script never tries to judge wording or pattern correctness.
+
+## Inputs
+
+| Argument          | Required | Default | Notes                                                                                  |
+| ----------------- | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `file`            | yes      | —       | Path to the built fragment. HTML for `wp-elementor`, Liquid for `shopify-section`.     |
+| `preset`          | yes      | —       | `wp-elementor` or `shopify-section`. Determines which checks apply.                    |
+| `output-dir`      | yes      | —       | Directory where `report.json` is written.                                              |
+| `compare-diffs`   | no       | —       | JSON from `sb-compare-visual` (full report or just the `structuredDiffs` array).       |
+| `memory-dir`      | no       | (auto)  | Override `<plugin>/memory` location. Auto-detects `~/.claude/similarbuild-memory` and the bundled `references/` fallback otherwise. |
+
+## Output
+
+A single JSON object printed to stdout AND saved to `{output-dir}/report.json`:
+
+```json
+{
+  "passed": false,
+  "file": "/abs/path/build.html",
+  "preset": "wp-elementor",
+  "violationCount": { "high": 2, "medium": 3, "low": 1 },
+  "violations": [
+    {
+      "group": "anti-pattern",
+      "id": "#5b",
+      "location": "selector `.hero__title`",
+      "issue": "`!important` without an ancestor in the selector — theme has both ancestor + !important so this loses anyway",
+      "candidateFix": "prefix `.hero__title` with the scope as ancestor: rewrite as `.{scope} .hero__title`",
+      "severity": "high",
+      "correlatedDiff": { "area": "h1", "issue": "font-size 24px vs 27px expected", "deltaPx": -3 }
+    }
+  ],
+  "report": "{output-dir}/report.json",
+  "inputs": { "file": "...", "preset": "...", "compareDiffs": "...", "memoryDir": "...", "memorySource": "bundled|home|flag" }
+}
+```
+
+`violations` is sorted **high → medium → low**, with cross-referenced (visual-diff-correlated) entries surfacing first within each severity. The orchestrator's first slice is always the most urgent fix.
+
+## Dependencies
+
+The host project must have `cheerio` installed (the SimilarBuild installer handles it). No browser, no native bindings. Node ≥ 20.
+
+## On Activation
+
+1. **Resolve inputs.** Collect `file`, `preset`, `output-dir`. Optional: `compare-diffs`, `memory-dir`.
+
+2. **Ensure `output-dir` exists.** `mkdir -p` it.
+
+3. **Run the script.** From the project root:
+
+   ```bash
+   node {skill-root}/scripts/review-checks.mjs \
+     --file "{built-file}" \
+     --preset "wp-elementor" \
+     --output-dir "{output-dir}" \
+     [--compare-diffs "{compare-report.json}"] \
+     [--memory-dir "{path-to-memory}"]
+   ```
+
+   The script handles: file read, cheerio parse, CSS extraction (also from `{% style %}` Liquid blocks), 8 anti-pattern checks, 12 design-quality checks, optional cross-reference with compare diffs, prioritization, and persistence. See `scripts/review-checks.mjs --help` for the full flag list.
+
+4. **Branch on exit code.**
+   - `0` — `passed: true`. Either zero violations or only `low`-severity ones. Ship it.
+   - `3` — `passed: false`, medium/high violations exist. **Not a script error.** Parse the JSON; the `violations` list is exactly what `sb-build-{wp,shopify}` expects as `fixHints` for the next re-roll.
+   - `1` — actual script error (missing dependency, malformed file). Surface stderr to the user and stop.
+   - `2` — invalid args. Fix the call.
+
+5. **Forward the JSON unchanged** to the caller. Do not summarize, mutate, or strip fields. Downstream consumers (the orchestrator's auto-correct loop, the HTML report) read every field directly.
+
+## Memory and presets
+
+The skill consults a memory directory in this order: `--memory-dir` flag → `~/.claude/similarbuild-memory/` → bundled `references/`. When present, files there should override the bundled defaults — they reflect the user's most recent curated knowledge. The bundled `references/review-rules.md` ships the canonical anti-patterns and design-quality rules so the skill is fully functional out of the box.
+
+The memory files are **data**, not code: adding a new anti-pattern is a `.md` edit, not a `.mjs` change. The orchestrator can hand-curate them and `sb-review-checks` picks them up next run.
+
+## Failure modes
+
+| Symptom                                              | Likely cause                                       | What to surface                                                                                  |
+| ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| Exit 1, stderr mentions `cheerio`                    | Dependency not installed                           | Pass stderr verbatim. Suggest `npm i cheerio`.                                                   |
+| Exit 1, "could not read"                             | Input file missing or not readable                 | Pass stderr verbatim. The build path may be stale — re-check what `sb-build-{wp,shopify}` returned. |
+| Exit 3 with only `low` severity in `violationCount`  | Should not happen — exit 3 implies med/high        | If you see this, file a bug — exit-code policy is wrong.                                         |
+| `inputs.memorySource: "bundled"` but you expected curated rules | The user-curated memory dir is not where the skill looks | Pass `--memory-dir` explicitly, or move the curated files to `~/.claude/similarbuild-memory/`.   |
+| `--compare-diffs` provided but no `correlatedDiff` annotations | The diffs file has no `severity: 'high'` entries  | Cross-reference only escalates on `high` diffs; med/low are advisory. This is by design.         |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/review-checks.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.
+- `<plugin>/memory/...` paths are inside the SimilarBuild plugin install — read them when present, fall back to bundled `references/` when absent.
+- `candidateFix` is a contract: every value names the selector, attribute, or property to change. Never emit prose-style suggestions ("improve X"). The auto-correct loop depends on this.

package/templates/skills/sb-review-checks/references/review-rules.md

@@ -0,0 +1,195 @@
+# Review Rules — anti-patterns + design quality (bundled fallback)
+
+This file is the **bundled fallback** for `sb-review-checks`. The skill reads it when no curated copy exists at `~/.claude/similarbuild-memory/` or wherever `--memory-dir` points. Treat the curated location (when present) as the source of truth — the user's most recent learning lives there. This file ships the canon so the skill is functional out of the box.
+
+These rules are **data**, not code: each entry has the same shape (id, symptom, check, fix template) and updates here don't require touching `scripts/lib/*.mjs`. The check functions in those libs implement detection; this file documents intent so a human reading the report knows *why* something was flagged.
+
+---
+
+## Group 1 — Anti-patterns (bootstrap canon)
+
+The 8 anti-patterns the script audits. `#7` (showing output before validating) and `#9` (replicating an image as inline SVG approximation when an asset exists) are **process-level** — they're prevented by `sb-validate-render` and `sb-extract-assets` respectively, so this skill does not re-check them.
+
+### #1 — Hero `100vh` in Elementor
+
+- **Preset:** `wp-elementor` only.
+- **Symptom:** mobile browser chrome eats viewport, hero clips below the fold.
+- **Check (mechanical):** any occurrence of `100vh` anywhere in the CSS.
+- **Fix template:** `replace 100vh with aspect-ratio + max-height on the hero container`.
+- **Severity:** high.
+
+### #2 — `<img>` with `height: 100%` for full-bleed hero
+
+- **Symptom:** Elementor injects `img { height: auto !important }` and clobbers the height.
+- **Check (mechanical):** an `<img>` under a `class~="hero"` ancestor with inline `style="… height: 100% …"`.
+- **Fix template:** `replace the <img> hero with background-image on the container`.
+- **Severity:** high.
+
+### #3 — Round-number opacity (eyeballed, not measured)
+
+- **Symptom:** opacity values `0.3`, `0.5`, `0.7` are nearly always guesses; real readings are arbitrary numbers like `0.42`.
+- **Check (mechanical):** regex `opacity\s*:\s*0?\.[357]` in any style block.
+- **Fix template:** `verify the alpha against inspection.tokens; comment-mark it /* alpha from inspection */ once verified`.
+- **Severity:** low.
+
+### #4 — `a { color: inherit }` in scoped CSS
+
+- **Symptom:** the anchor inherits the themed ancestor color, brand color is lost.
+- **Check (mechanical):** any rule whose selector ends in `a` (or `a.x`/`a:hover`) with `color: inherit` in the body.
+- **Fix template:** `replace color: inherit with a literal hex from inspection.tokens`.
+- **Severity:** medium.
+
+### #5 — `<button>` decorative without defensive specificity
+
+- **Symptom:** theme `.elementor *` rules win over single-class selectors.
+- **Check (mechanical):** a rule whose selector contains `button|btn|cta`, has neither a descendant combinator (whitespace) nor a doubled class chain (`.x.x`), and styles background/color/font.
+- **Fix template:** `chain the scope as ancestor: rewrite selector with the scope class as ancestor and double the modifier class`.
+- **Severity:** high.
+
+### #5b — `!important` without an ancestor in the selector
+
+- **Symptom:** theme has both ancestor specificity AND !important, so a bare-selector !important rule still loses.
+- **Check (mechanical):** a rule whose body contains `!important` and whose selector branches all lack a descendant combinator before the rightmost compound selector.
+- **Fix template:** `prefix the selector with the scope as ancestor`.
+- **Severity:** high.
+
+### #6 — Overlap-image modeled as a box on the wrapper
+
+- **Symptom:** the colored band is rendered as a sibling/box on the column wrapper instead of a `::before` on the section. Stacking is fragile and breaks at narrow widths.
+- **Check (mechanical):** a `::before` rule whose selector targets a `wrap|wrapper|container|inner` class with `position: absolute` + an inset/edge declaration.
+- **Fix template:** `move the ::before to the section selector; set position: relative on the section and z-index: -1 on the ::before`.
+- **Severity:** medium.
+
+### #8 — Inline SVG impostor where a raster `<img>` belongs
+
+- **Symptom:** a hand-drawn SVG approximating a product photo. Looks "off" and misses real-world detail.
+- **Check (mechanical):** an `<svg>` with `viewBox` whose larger dimension ≥ 400, ≥ 2 `<path>` children, and a `class`/parent class matching `product|photo|hero|image|card|variant`.
+- **Fix template:** `replace the <svg> with <img src="{assetsMap[originalUrl].localPath}" alt="…" loading="lazy">`.
+- **Severity:** medium.
+
+---
+
+## Group 2 — Design quality (a11y / performance / web standards)
+
+12 baseline checks. These are not opinions — they are baselines every production fragment must clear. The script flags presence/absence; the LLM judges semantic quality (e.g. "is this alt text *meaningful*?").
+
+### a11y-button-aria — icon-only `<button>` without `aria-label`
+
+- **Check:** a `<button>` whose visible text is empty (or one emoji/glyph) with no `aria-label`/`aria-labelledby` and no inner `<img alt="…">`.
+- **Fix:** `add aria-label="<inferred action>"` (Close, Open menu, Search, etc).
+- **Severity:** high.
+
+### a11y-img-alt — `<img>` missing `alt`
+
+- **Check:** any `<img>` with no `alt` attribute (empty `alt=""` is fine — that means decorative, intentional).
+- **Fix:** `add alt="" (decorative) or alt="<short description>"`.
+- **Severity:** high.
+
+### a11y-heading-hierarchy — broken outline
+
+- **Checks:**
+  - first heading is `<h3>` or deeper (no h1/h2 above) → medium.
+  - multiple `<h1>` elements → medium.
+  - skip in level (`<h2>` followed by `<h4>`) → low.
+- **Fix:** specific to the case (demote, change to h2, fix the level).
+
+### a11y-button-type — `<button>` without explicit `type`
+
+- **Check:** `<button>` with no `type` attribute (or a non-standard value).
+- **Fix:** `add type="button"`.
+- **Severity:** medium.
+
+### a11y-nav-semantic — main nav as `<div>`
+
+- **Check:** a `<div>` with class containing `nav|menu|navigation` (excluding `footer`/`sub`/`breadcrumb`) that contains ≥ 2 `<a>` children and is not inside a `<nav>`.
+- **Fix:** `change <div class="…"> to <nav class="…" aria-label="Main">`.
+- **Severity:** medium.
+
+### perf-img-lazy — non-hero `<img>` without `loading="lazy"`
+
+- **Check:** an `<img>` that is not the hero (heuristic: has `fetchpriority=high`, ancestor class `hero`, or first `<img>` in document) and does not declare `loading="lazy"`/`loading="eager"`.
+- **Fix:** `add loading="lazy"`.
+- **Severity:** medium.
+
+### perf-hero-preload — hero without preload link
+
+Two-step detection (Pattern #25 of the plan — without it, builds where the hero is a CSS `background-image` get a false positive on the logo `<img>`):
+
+1. **CSS background-image hero.** Scan the scope CSS for a rule whose selector
+   is a single root-scope class (`.foo` or `.foo:pseudo`, no descendant
+   combinator, no `__` BEM modifier) and whose body declares
+   `background-image: url(...)`. The `url(...)` of the **first** matching rule
+   IS the hero — verify a `<link rel="preload" as="image" href="<bg-url>">`
+   exists, flag against that URL otherwise.
+
+2. **`<img>` hero (only when no CSS-bg hero was found).** Confidence-tiered:
+   `fetchpriority="high"` → ancestor class containing `hero` → `src`/`alt`
+   contains `hero|banner|cover` → declared width ≥ 800px → first `<img>` (last
+   resort, **skipped** here so logos don't false-positive).
+
+3. **Neither tier matches.** Skip the check entirely — no false positive on
+   pages without an obvious hero.
+
+- **Fix:** `add <link rel="preload" as="image" href="{heroUrl}">` at the top of the fragment.
+- **Severity:** medium.
+
+### perf-font-display — Google Fonts without `&display=swap`
+
+- **Check:** `<link rel="stylesheet" href="…fonts.googleapis.com…">` whose href has no `display=swap` query parameter.
+- **Fix:** `append &display=swap to the href`.
+- **Severity:** medium.
+
+### perf-fetchpriority-hero — Shopify hero without `fetchpriority="high"`
+
+- **Preset:** `shopify-section` only.
+- **Check:** the hero `<img>` has no `fetchpriority="high"`.
+- **Fix:** `add fetchpriority="high" to the hero <img>`.
+- **Severity:** low.
+
+### web-srcset-responsive — wide `<img>` without `srcset`
+
+- **Check:** an `<img>` with explicit width > 800px (via `width=…` or inline `style="width: …px"`) and no `srcset` attribute. Without an explicit width we don't flag — too noisy.
+- **Fix:** `add srcset + sizes; the orchestrator can fill from inspection`.
+- **Severity:** low.
+
+### web-modal-dialog — modal as `<div>`
+
+- **Check:** a `<div>` with `role="dialog"` or class containing `modal` that is not inside a `<dialog>`.
+- **Fix:** `change to <dialog>; open with showModal(), close with close()`.
+- **Severity:** medium.
+
+### web-preconnect-fonts — Google Fonts without preconnect
+
+- **Check:** at least one `<link rel="stylesheet" href="…fonts.googleapis.com…">` exists, but no preconnect to `fonts.googleapis.com` and/or `fonts.gstatic.com`.
+- **Fix:** `add the missing <link rel="preconnect" href="…"> entries before the Google Fonts stylesheet`.
+- **Severity:** low.
+
+---
+
+## Group 3 — Cross-reference (when `--compare-diffs` is supplied)
+
+Not a separate check list — a layer applied on top of groups 1 & 2.
+
+- For each violation, look up its `location` against high-severity entries in `compareDiffs.structuredDiffs`. If they overlap (e.g. a button-related violation and a high-severity button color diff), the violation is escalated to `severity: high` and tagged with `correlatedDiff`.
+- For each high-severity diff with no static-rule backing, synthesize a violation directly from the diff measurements so it joins the prioritized list. Its `candidateFix` names the concrete value to change ("update `h1` from build value `24px` to live-page value `27px`").
+- Result: one prioritized list. The orchestrator never has to reason across two parallel sources.
+
+---
+
+## Output contract
+
+Every emitted violation has the shape:
+
+```json
+{
+  "group": "anti-pattern" | "a11y" | "performance" | "web-standards" | "visual-diff" | "design-quality",
+  "id": "#5b" | "a11y-button-aria" | "diff-h1",
+  "location": "selector `…`" | "<tag …>" | "style block line N",
+  "issue": "<one-sentence human-readable description of the problem>",
+  "candidateFix": "<specific patch instruction — names the selector/attribute/property>",
+  "severity": "high" | "medium" | "low",
+  "correlatedDiff": { "area": "…", "issue": "…", "deltaPx": -3 }   // optional, only when cross-referenced
+}
+```
+
+The hard rule: `candidateFix` must be specific enough that `sb-build-{wp,shopify}` can apply it programmatically as a `fixHint`. Generic prose ("improve specificity", "fix accessibility") is forbidden — that is the failure mode this skill exists to prevent.