>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588746. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Sprint 3 &mdash; Visual Fidelity &amp; Verification. This is a roll-up meta-issue tracking the QA-loop defects that allow regressions to ship to the live CMS. Sprint 1 fixed site-analyzer capture quality. Sprint 2 fixed parallelism and gate messaging. Sprint 3 closes the verification gap on top of those foundations.</p> <p>Once good reference material exists (Sprint 1) and the skill dispatches correctly (Sprint 2), the QA loop must actually detect regressions before they hit the live site &mdash; not after. Two recurring user complaints point to the same gap: "your analysis broke the site more, things look more disoriented and not in place than before" and "your sweep is bad, the page looks nothing alike &hellip; compare component level not just an overview of page." No systematic measurement-first protocol exists in the current skill. This sprint closes that gap end-to-end: per-component baselines (3-01), page-level Storybook drafts (3-02), three-tier CSS measurement (3-03), one-component-at-a-time discipline (3-04), and a revision tracking system (3-05).</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <p>See each child issue for repro steps specific to that defect.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Land the five child issues in suggested order. Order rationale:</p> <ul> <li><strong>3-01 first</strong> &mdash; smallest, lowest-risk change (update <code>storybook-qa</code> agent to always capture a built screenshot at issue-filing time). Everything that follows depends on having reliable before-fix baselines.</li> <li><strong>3-02 second</strong> &mdash; adding a mandatory Phase 3.7 (Storybook page stories before CMS push) is a skill-structure change that does not touch any comparison logic. Can be done in parallel with 3-01.</li> <li><strong>3-03 third</strong> &mdash; the three-tier comparison protocol (structural DOM &rarr; CSS measurement via <code>evaluate_script</code> &rarr; screenshot) is the core intellectual change of the sprint. Builds on 3-01's baseline convention.</li> <li><strong>3-04 fourth</strong> &mdash; one-component-at-a-time upload discipline is the enforcement side of 3-03. Once the measurement protocol exists, each component can be verified before the next is touched.</li> <li><strong>3-05 last</strong> &mdash; full revision tracking (pre/current/post three-way diff in a <code>revisions/</code> directory) is the long-term systematic solution that builds on all of the above.</li> </ul> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>3-01 &mdash; Issue files missing before-fix screenshots (P1, Feature Request)</li> <li>3-02 &mdash; Page-level Storybook stories not created before CMS composition (P1, Feature Request)</li> <li>3-03 &mdash; Visual sweep too coarse &mdash; compare component level via three-tier protocol (P1, Bug Report)</li> <li>3-04 &mdash; Aggressive multi-component changes regress the site (P0, Bug Report)</li> <li>3-05 &mdash; Component revision tracking &mdash; before/current/after comparison (P2, Feature Request)</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None at the sprint level &mdash; see child issues. Storybook page stories (3-02) become a mandatory pre-CMS visual artifact.</p> <h3 id="summary-api-changes">API changes</h3> <p>None at the sprint level &mdash; see child issues. The <code>visual-comparison</code> skill gains a <code>compare_three_way</code> operation (3-05).</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact convention: <code>docs/migration/components/&lt;name&gt;/revisions/</code> directory with <code>source.png</code>, <code>N-pre.png</code>, <code>N-post.png</code>, <code>revisions.jsonl</code> (3-05). New mandatory fields on issue files: <code>source_screenshot</code>, <code>built_screenshot</code> (3-01). New gate artifact for Phase 3.7 (3-02).</p> <h3 id="summary-definition-of-done">Definition of done</h3> <ul> <li><code>storybook-qa.md</code> always captures <code>source_screenshot</code> + <code>built_screenshot</code> before filing any issue (3-01).</li> <li><code>component-fixer.md</code> refuses to proceed if <code>built_screenshot</code> is missing from the issue file (3-01).</li> <li>SKILL.md has a Phase 3.7 gate: all pages have a Storybook page story with real content before Phase 4 upload proceeds (3-02).</li> <li><code>visual-verifier.md</code> implements three-tier comparison: structural DOM check &rarr; CSS property measurement via <code>evaluate_script</code> &rarr; screenshot (3-03).</li> <li>Ralph Loop prompt includes explicit "ONE component at a time &mdash; upload, verify, then proceed" rule (3-04).</li> <li><code>component-fixer.md</code> implements per-component pre-fix screenshot capture before any code change (3-04).</li> <li>A <code>revisions/</code> directory convention is documented and <code>component-fixer.md</code> writes <code>N-pre.png</code> / <code>N-post.png</code> on every fix (3-05).</li> <li>The revision system computes or logs a direction signal: post-fix is more or less similar to source than pre-fix was (3-05).</li> </ul> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Sprint folder: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-3-Visual-Fidelity/</code></li> <li>Sprint README: <code>Sprint-3-Visual-Fidelity/README.md</code></li> <li>Top-level issues README: <code>RESEARCH-2026-04-28/99-final/ISSUES/README.md</code></li> <li>Recommendation source: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code></li> <li>Consolidated issues: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code></li> <li>Q3 working implementation: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q3-records-5768-to-8651/visual-fidelity-iteration-pattern.md</code></li> <li>Pattern catalogue: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect;&sect; P2, P12, P15, P18</li> </ul> <h3 id="summary-child-issues">Child issues</h3> <p>Linked child issues for this sprint (auto-rendered with status badges):</p> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588776" title="Status: Closed (fixed)">#3588776: [Sprint 3] Issue files missing before-fix screenshots &mdash; fixer working blind</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588777" title="Status: Closed (fixed)">#3588777: [Sprint 3] Page-level Storybook stories not created before CMS push</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588778" title="Status: Closed (fixed)">#3588778: [Sprint 3] Visual sweep too coarse &mdash; three-tier component-level comparison</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588779" title="Status: Closed (fixed)">#3588779: [Sprint 3] Aggressive multi-component changes regress the site</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588780" title="Status: Closed (fixed)">#3588780: [Sprint 3] Component revision tracking &mdash; before/current/after comparison</a></span></li> </ul>