similarbuild 0.3.4 → 0.4.0

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

@@ -198,104 +198,11 @@ async function main() {
       }
     })
 
-    // §V03-0a — lazy-hydration wait WHILE SCROLLED TO BOTTOM. Many
-    // Shopify themes populate footer menus (Contact, Privacy Policy,
-    // Collections links) via <store-footer-menu>-style custom elements
-    // only AFTER the host intersects the viewport. Wait here, with the
-    // footer in view, for any <footer> <ul> to gain children or for
-    // <footer> <a href> count to reach >= 3.
-    log('waiting for lazy-hydrated footer content (max 5s)')
-    try {
-      await page.waitForFunction(
-        () => {
-          const lists = document.querySelectorAll('footer ul, [class*="footer"] ul')
-          for (const ul of lists) {
-            if (ul.children.length > 0) return true
-          }
-          const links = document.querySelectorAll('footer a[href], [class*="footer"] a[href]')
-          return links.length >= 3
-        },
-        { timeout: 5000 },
-      )
-      log('footer content hydrated')
-    } catch (_) {
-      log('footer hydration timeout — proceeding')
-    }
-
-    // §V03-0a — capture hydrated chrome HTML WHILE STILL IN VIEW.
-    // Shopify themes that populate footer menus on viewport intersection
-    // sometimes tear the content down when the host leaves the viewport.
-    // The walker can't see torn-down menus. Snapshot the relevant
-    // subtrees here, before we scroll back to the top for layout reads,
-    // and stash them on `window` for extractInPage to read during walk.
-    log('snapshotting hydrated header/footer HTML for downstream use')
-    await page.evaluate(() => {
-      function pickFooter() {
-        const candidates = document.querySelectorAll(
-          'footer, [class*="footer"][class*="section"], [role="contentinfo"]',
-        )
-        let best = null
-        for (const el of candidates) {
-          const r = el.getBoundingClientRect()
-          if (r.height < 50) continue
-          const links = el.querySelectorAll('a[href]').length
-          const inputs = el.querySelectorAll('input,form').length
-          const score = links + inputs * 2 + r.height / 100
-          if (!best || score > best.score) best = { el, score }
-        }
-        return best?.el || null
-      }
-      function pickHeader() {
-        const candidates = document.querySelectorAll(
-          'header, [class*="header"][class*="section"], [role="banner"]',
-        )
-        let best = null
-        for (const el of candidates) {
-          const r = el.getBoundingClientRect()
-          if (r.height < 30) continue
-          const links = el.querySelectorAll('a[href]').length
-          const score = links + r.height / 100
-          if (!best || score > best.score) best = { el, score }
-        }
-        return best?.el || null
-      }
-      const footer = pickFooter()
-      const header = pickHeader()
-      window.__sbHydratedFooter = footer
-        ? {
-            html: footer.outerHTML,
-            bbox: (() => {
-              const r = footer.getBoundingClientRect()
-              return {
-                x: Math.round(r.x + window.scrollX),
-                y: Math.round(r.y + window.scrollY),
-                w: Math.round(r.width),
-                h: Math.round(r.height),
-              }
-            })(),
-          }
-        : null
-      window.__sbHydratedHeader = header
-        ? {
-            html: header.outerHTML,
-            bbox: (() => {
-              const r = header.getBoundingClientRect()
-              return {
-                x: Math.round(r.x + window.scrollX),
-                y: Math.round(r.y + window.scrollY),
-                w: Math.round(r.width),
-                h: Math.round(r.height),
-              }
-            })(),
-          }
-        : null
-    })
-
     // Return to the top before layout reads. content-visibility:auto on
-    // viewport-distant nodes returns {w:0,h:0} bboxes — walker can't
-    // read layout from the bottom. 1.2s settle for any re-hydration.
+    // viewport-distant nodes returns {w:0,h:0} bboxes — walker reads from
+    // the at-top state. 800ms settle for any re-hydration.
     await page.evaluate(() => window.scrollTo(0, 0))
-    await page.waitForTimeout(1200)
+    await page.waitForTimeout(800)
 
     // Force-eager: any <img loading="lazy"> that didn't intersect during scroll
     // gets rewritten to eager and re-fetched. <picture> sources too.
@@ -454,88 +361,7 @@ async function main() {
         return slug || 'section'
       }
 
-      // §V03-4 image-block detection. A section is an image-block when
-      // its visible content is dominated by a single <img>: either by
-      // bbox coverage (img takes ≥80% of section area) OR by a known
-      // wrapper-class pattern (Shopify Dawn / OS 2.0 themes use specific
-      // wrapper classes like `product-info__image` to delimit a region
-      // whose entire visual content is one CDN-hosted SVG/PNG/JPG asset).
-      // The composer (sb-build-wp §V03-4 rule A) treats image-block
-      // sections as "download asset + emit <img src>" — NEVER tries to
-      // reproduce the visual contents in HTML/CSS.
-      const IMAGE_BLOCK_WRAPPER_PATTERNS = [
-        /product-info__image/i,
-        /image-with-text/i,
-        /\bhero-image\b/i,
-        /\btrust-badges\b/i,
-        /\bfeatures-points\b/i,
-        /\bmothers?-day\b/i,
-        /\bsingle-image\b/i,
-        /\bbanner-image\b/i,
-        /\bguarantee-card\b/i,
-        /\bbest-fit-size-chart\b/i,
-      ]
-      function classifyAsImageBlock(node) {
-        if (!node || typeof node !== 'object') return null
-        const sectionBbox = node.bbox
-        if (!sectionBbox || !sectionBbox.h || !sectionBbox.w) return null
-        const sectionArea = sectionBbox.h * sectionBbox.w
-        if (sectionArea <= 0) return null
-        // Match by wrapper-class pattern on the node itself OR any
-        // descendant (the wrapper might be a child of the section root).
-        function findClassMatch(n) {
-          if (!n || typeof n !== 'object') return null
-          if (Array.isArray(n.classes)) {
-            for (const cls of n.classes) {
-              for (const pat of IMAGE_BLOCK_WRAPPER_PATTERNS) {
-                if (pat.test(cls)) return cls
-              }
-            }
-          }
-          if (Array.isArray(n.children)) {
-            for (const c of n.children) {
-              const m = findClassMatch(c)
-              if (m) return m
-            }
-          }
-          return null
-        }
-        const classMatch = findClassMatch(node)
-        // Find the largest <img> descendant by bbox area.
-        let bestImg = null
-        function findBiggestImg(n) {
-          if (!n || typeof n !== 'object') return
-          if (n.tag === 'img' && n.bbox && n.bbox.h > 0 && n.bbox.w > 0) {
-            const a = n.bbox.h * n.bbox.w
-            if (!bestImg || a > bestImg.area) {
-              const src = (n.attrs && (n.attrs.src || n.attrs.srcset)) || ''
-              bestImg = { area: a, bbox: n.bbox, src }
-            }
-          }
-          if (Array.isArray(n.children)) {
-            for (const c of n.children) findBiggestImg(c)
-          }
-        }
-        findBiggestImg(node)
-        const imgArea = bestImg ? bestImg.area : 0
-        const coverage = sectionArea > 0 ? imgArea / sectionArea : 0
-        if (classMatch || coverage >= 0.8) {
-          return {
-            reason: classMatch
-              ? `wrapper-class:${classMatch}`
-              : `img-coverage:${(coverage * 100).toFixed(0)}%`,
-            imgSrc: bestImg ? bestImg.src : null,
-            imgBbox: bestImg ? bestImg.bbox : null,
-            coverage,
-          }
-        }
-        return null
-      }
-      const sourceDom = result.domLive
-        ? Array.isArray(result.domLive)
-          ? result.domLive
-          : [result.domLive]
-        : result.dom
+      const sourceDom = result.dom
 
       // Find the host container (body or main) — walk in one level and
       // pick the node with the most children + largest bbox.
@@ -574,7 +400,6 @@ async function main() {
               sectionList.push({
                 sectionType: labelFromNode(grand),
                 bbox: grand.bbox,
-                imageBlock: classifyAsImageBlock(grand),
               })
             }
           }
@@ -586,7 +411,6 @@ async function main() {
         sectionList.push({
           sectionType: labelFromNode(child),
           bbox,
-          imageBlock: classifyAsImageBlock(child),
         })
       }
 
@@ -647,7 +471,6 @@ async function main() {
               sectionType: sec.sectionType,
               bbox: sec.bbox,
               path: cropPath,
-              imageBlock: sec.imageBlock || null,
             })
           } catch (err) {
             log(`section crop ${idx} ${sec.sectionType} failed: ${err?.message || err}`)
@@ -1297,11 +1120,6 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   // iframes (Klaviyo embeds, recaptcha) are recorded as opaque rectangles.
   let shadowDOMTraversed = false
   let shadowRootCount = 0
-  // §V03-C — counts hosts whose shadow tree was successfully re-serialized
-  // via getHTML+parseHTMLUnsafe and re-walked into a flattened light-DOM
-  // representation. 0 means the post-render shadow-flatten phase was either
-  // unavailable, skipped, or hit zero open roots.
-  let shadowSerializedHostCount = 0
   const warnings = []
   const externalIframes = []
   function classifyIframePurpose(src) {
@@ -1752,198 +1570,17 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   const dom = [walk(root, 0)].filter(Boolean)
   const { sectionType, sectionBoundingBox } = findSectionAndBox(root, !!selector)
 
-  // §V03-C — Shadow DOM serialization via getHTML + parseHTMLUnsafe.
-  // walk() above only sees light DOM and `.shadowRoot.children` direct.
-  // Custom elements whose shadow tree is populated by JS (Shopify
-  // <x-product-form>, <price-list>, <variant-radios>, <store-footer-menu>)
-  // expose content that the children-only walker can technically read,
-  // but `<slot>`-projected content and content composed from declarative
-  // shadow DOM gets fragmented. getHTML({ serializableShadowRoots: true })
-  // emits a single HTML string with `<template shadowrootmode="open">`
-  // declarations inline; parseHTMLUnsafe re-attaches those as live shadow
-  // roots in a parsed document, which the same walk() can then flatten
-  // uniformly. Layout (bbox/computedStyle) on the parsed doc is detached
-  // and returns UA defaults — that's an acknowledged trade-off; the
-  // structural content (tags, classes, attrs, text, src) is what makes
-  // PDP gallery/price/variants visible to the composer downstream.
-  const originalShadowRootCount = shadowRootCount
-  const originalShadowDOMTraversed = shadowDOMTraversed
-  // §V03-C — preserve a snapshot of the live-walker dom[] before any
-  // potential substitution. If the re-walk replaces dom[] with the
-  // shadow-flattened tree (which carries detached parsedDoc bboxes
-  // === {0,0,0,0}), downstream consumers that need real layout (e.g.
-  // /build-site Step 3.5e --crop-live-bbox for header/footer compare)
-  // can fall back to domLive. When substitution doesn't fire, domLive
-  // is left null and consumers use dom[] as-is.
-  let domLive = null
-  try {
-    if (typeof document.documentElement.getHTML === 'function' &&
-        typeof Document.parseHTMLUnsafe === 'function') {
-      const hostsSeen = new Set()
-      const hostsCollected = []
-      function collectHostsFrom(el) {
-        if (!el) return
-        if (el.shadowRoot && !hostsSeen.has(el)) {
-          hostsSeen.add(el)
-          hostsCollected.push(el)
-          for (const child of el.shadowRoot.children) collectHostsFrom(child)
-        }
-        for (const child of el.children) collectHostsFrom(child)
-      }
-      collectHostsFrom(document.documentElement)
-
-      if (hostsCollected.length > 0) {
-        const html = document.documentElement.getHTML({
-          serializableShadowRoots: true,
-          shadowRoots: hostsCollected.map((h) => h.shadowRoot),
-        })
-        const parsedDoc = Document.parseHTMLUnsafe(html)
-        const parsedRoot = selector
-          ? parsedDoc.querySelector(selector)
-          : parsedDoc.body
-        if (parsedRoot) {
-          const flattened = walk(parsedRoot, 0)
-          // §V03-C safety guard: only substitute the live dom[] if the
-          // re-walk did not lose value on EITHER axis (nodes or aggregate
-          // text chars). parseHTMLUnsafe returns a detached doc;
-          // getComputedStyle/getBoundingClientRect degrade to UA defaults
-          // (zero bbox, empty computed). On pages where shadow flattening
-          // adds value (PDPs Shopify with populated custom elements) the
-          // gain is large; on pages without that workload (policies,
-          // plain HTML), the re-walk can lose content because hydrated
-          // shadow content visible to the live walker doesn't reproduce
-          // on the detached tree. When that happens, keep the live
-          // walker result and surface a warning.
-          function measureTree(arr) {
-            let nodes = 0
-            let textChars = 0
-            const stack = Array.isArray(arr) ? [...arr] : [arr]
-            while (stack.length) {
-              const node = stack.pop()
-              if (!node || typeof node !== 'object') continue
-              nodes++
-              if (typeof node.text === 'string') textChars += node.text.length
-              if (Array.isArray(node.children)) {
-                for (const c of node.children) stack.push(c)
-              }
-            }
-            return { nodes, textChars }
-          }
-          if (flattened) {
-            const orig = measureTree(dom)
-            const flat = measureTree([flattened])
-            if (flat.nodes >= orig.nodes && flat.textChars >= orig.textChars) {
-              // Snapshot the live walker result BEFORE substitution so
-              // downstream consumers that depend on real layout (bbox
-              // values are zero on the parsed detached doc) can fall
-              // back when needed — see §V03-C domLive comment above.
-              domLive = dom.length === 1 ? dom[0] : [...dom]
-              dom.length = 0
-              dom.push(flattened)
-              shadowSerializedHostCount = hostsCollected.length
-            } else {
-              warnings.push({
-                code: 'shadow-flatten-skipped-lossy',
-                message: `re-walk lossy: nodes ${flat.nodes} vs ${orig.nodes}, textChars ${flat.textChars} vs ${orig.textChars}; keeping live walker result`,
-              })
-            }
-          }
-          // The re-walk of the parsed (detached) doc re-discovers shadow
-          // roots that parseHTMLUnsafe re-attached, so it would
-          // double-count if we let those increments leak. Restore the
-          // canonical live counts here.
-          shadowRootCount = originalShadowRootCount
-          shadowDOMTraversed = originalShadowDOMTraversed
-        }
-      }
-    } else {
-      warnings.push({
-        code: 'shadow-serialize-unavailable',
-        message:
-          'getHTML or Document.parseHTMLUnsafe not available; shadow DOM falls back to .shadowRoot.children walk (v0.2.x behavior)',
-      })
-    }
-  } catch (err) {
-    shadowRootCount = originalShadowRootCount
-    shadowDOMTraversed = originalShadowDOMTraversed
-    warnings.push({
-      code: 'shadow-serialize-failed',
-      message: String(err && err.message ? err.message : err),
-    })
-  }
-
-  // §V03-0a — extract structured content from the hydrated-chrome
-  // HTML snapshots taken before scroll-back. Shopify themes that
-  // populate menus on viewport intersection may have torn those down
-  // by the time the walker runs. The snapshots preserve the truth.
-  function extractChrome(snapshot) {
-    if (!snapshot || !snapshot.html) return null
-    let parsed
-    try {
-      parsed = new DOMParser().parseFromString(snapshot.html, 'text/html')
-    } catch (_) {
-      return { ...snapshot, links: [], headings: [], inputs: [], forms: [], images: [] }
-    }
-    const root = parsed.body.firstElementChild || parsed.body
-    const norm = (s) => (s || '').replace(/\s+/g, ' ').trim()
-    const links = Array.from(root.querySelectorAll('a[href]'))
-      .map((a) => ({
-        href: a.getAttribute('href') || '',
-        text: norm(a.textContent),
-        label: a.getAttribute('aria-label') || null,
-      }))
-      .filter((l) => l.href && (l.text || l.label))
-    const headings = Array.from(root.querySelectorAll('h1, h2, h3, h4, h5, h6, p.bold, .footer__block-title, [class*="heading"]'))
-      .map((h) => ({ tag: h.tagName.toLowerCase(), text: norm(h.textContent) }))
-      .filter((h) => h.text)
-    const inputs = Array.from(root.querySelectorAll('input')).map((i) => ({
-      type: i.getAttribute('type') || 'text',
-      name: i.getAttribute('name') || null,
-      placeholder: i.getAttribute('placeholder') || null,
-      required: i.hasAttribute('required'),
-      ariaLabel: i.getAttribute('aria-label') || null,
-    }))
-    const forms = Array.from(root.querySelectorAll('form')).map((f) => ({
-      action: f.getAttribute('action') || null,
-      method: f.getAttribute('method') || 'get',
-      id: f.getAttribute('id') || null,
-    }))
-    const images = Array.from(root.querySelectorAll('img'))
-      .map((img) => ({
-        src: img.getAttribute('src') || '',
-        alt: img.getAttribute('alt') || '',
-        width: img.getAttribute('width') || null,
-        height: img.getAttribute('height') || null,
-      }))
-      .filter((img) => img.src)
-    return {
-      html: snapshot.html,
-      bbox: snapshot.bbox,
-      links,
-      headings,
-      inputs,
-      forms,
-      images,
-    }
-  }
-  const hydratedHeader = extractChrome(window.__sbHydratedHeader)
-  const hydratedFooter = extractChrome(window.__sbHydratedFooter)
-
   return {
     sectionType,
     sectionBoundingBox,
     tokens,
     dom,
-    domLive,
     pseudoElements,
     imgUrls,
     shadowDOMTraversed,
     shadowRootCount,
-    shadowSerializedHostCount,
     warnings,
     externalIframes,
-    hydratedHeader,
-    hydratedFooter,
   }
 }
 

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

@@ -1,113 +0,0 @@
----
-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.