[noeltock]

Problem

Rendered delivery can pass the block gate while losing layout, content or interaction. Make matched visual comparison and correction the default skill workflow. Closes #198.

Solution

The skill now finishes rendered work with desktop/mobile comparison, source-located corrections and native editor proof. A clean first comparison ends there. Source-only work, an unavailable target or an explicit skip still delivers with an honest verification gap. This adds no deployment authority and changes no CLI/library behaviour.

Behaviour	Read first	Proof
Rendered finishing is the default	skills/block-runner/SKILL.md, references/VISUAL.md	Default and exception paths stated explicitly
Compare content, responsive regions and interaction	references/VISUAL.md	Matched captures and measured widths, wrapping, positions and overflow
Correct source, regenerate and preserve evidence	dev/test/fixtures/visual-review	Strict before/after compilation and hash-confirmed local site apply
Native editing survives delivery	Fixture README / editor captures	Page and template-part edit/save/reopen, saved readback and frontend observation

Diff

18 files, +321 / −1, including 8 synthetic evidence images. No runtime code, new helper, command or dependency.

 skills/block-runner/SKILL.md
+ rendered delivery → references/VISUAL.md by default
 GUIDE.md / SITE.md
+ concise link to the finishing workflow
 references/VISUAL.md
+ content → matched desktop/mobile regions → targeted measurements
+ source correction → existing gate/delivery → recapture → native edit/save/reopen
 dev/test/fixtures/visual-review/
+ long-copy page + shared template part, authored reference and seeded CSS defects
+ corrected source CSS, replay instructions and inspected before/after/editor captures

Testing & verification

Reviewed revision: f6bbf0a. Node 22.23.1, local WordPress 7.1 / PHP 8.4.27; Chromium 155 for paired frontend inspection, Chrome 154 for native editing.

• npm run build, npm run check:private, git diff --check, npm run pack:check: passed.
• npx --no-install vitest run dev/test/skill.test.ts: 3 tests passed.
• Relative links in the new reference and fixture README resolve.
• node dist/cli.js site compile dev/test/fixtures/visual-review/site.intent.json --asset-root dev/test/fixtures/visual-review --out /tmp/visual-review-before --strict --json: no diagnostics. Corrected source also compiled strictly without diagnostics.
• Existing site plan / hash-confirmed site apply completed on the disposable local target; original plans/journals/readbacks were retained.
• At matched 1280×900 and 390×844 viewports, the article width corrected 480→720px, closing part 440→960px, and mobile highlight 520→342px. Mobile document overflow corrected 544→390px. WordPress first-child spacing corrected to 48px desktop / 24px mobile. Region text, widths, heights, positions and alignment then matched the authored reference.
• Edited the page paragraph and template-part paragraph through actual native controls, saved, reopened, and confirmed the changed text in saved content and the frontend. Restored the original text through those controls. validate on restored markup: page 8/8 valid, part 2/2 valid, no warnings.

Not verified: independent reviewer replay and production behaviour. The fixture is a controlled demonstration, not a broad converter-fidelity benchmark. Missing-reference/source-only exception paths were reviewed as instructions, not measured in a paid model run.

Visual evidence

Monolith native WordPress homepage, before and after visual finishing. Desktop: 1440×1000; mobile: 390×844. Corrections restore the source fonts, keep the mobile header on one row, prevent the New badge from wrapping and preserve command punctuation. The animated artwork is captured at different phases.

Desktop before	Desktop after

Mobile before	Mobile after

These captures demonstrate the homepage finishing pass, not full-site fidelity or interaction acceptance. The separate synthetic replay fixture retains the reproducible seeded defects and native editor proof.

Risk / rollout

The added default costs a bounded rendered comparison when a target exists; a clean comparison requires no correction loop. CLI/API callers remain unchanged. Detection: use the seeded fixture and inspect the retained captures, including clipping rather than only document overflow. Rollback: revert the skill/reference/fixture changes; no runtime migration is involved.

⟁ Written by AI. Context window fully weaponized.