Fold demo-build learnings: mechanical visual-QA design gate + detector-authoring traps

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude skills for Dynamicweb 10 — organized by task domain, bundled by role.",
-    "version": "4.11.0"
+    "version": "4.11.1"
   },
   "plugins": [
     {

CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to the Dynamicweb Skills plugin are recorded here. The
 `version` field in `.claude-plugin/marketplace.json` tracks these entries.
 
+## [4.11.1]
+
+Folds a demo-build session's design-quality-gate learnings into the demo skills' visual-QA,
+orchestrator, and re-skin references: a mechanical definition-of-done that catches the polish
+defects a screenshot glance skips, plus the authoring traps that make such a gate pass silently.
+
+### Added
+- **Image-band height is a Tier-1 visual-QA item, mechanically gated**
+  (`dw-demo-base/references/visual-qa.md` detector + eyeball + symptom table + DoD;
+  `dw-demo-swift/references/re-skin.md` verification): stock image components carry no
+  serialized height field, so a swapped-in portrait crop or slider cover-card renders at full
+  column-width height and dominates the fold — a defect distinct from a stretched image. A new
+  `tall` detector flags any image band taller than a configured fraction of the viewport; the
+  durable fix is a Tier-1 theme-CSS cap (`aspect-ratio` + `max-height` + `object-fit: cover`).
+- **PLP list asserts row-presence AND per-row content, not HTTP 200**
+  (`dw-demo-base/references/visual-qa.md`): a list-mode product page can return 200 while
+  rendering zero rows (empty/not-yet-repopulated index, mis-scoped shop). A new detector asserts
+  row count ≥ `minRows` and that each row carries its required-field selectors (thumbnail / SKU /
+  price / add-to-cart); an empty or field-short list behind 200 is a named finding, never a pass.
+- **The programmatic detectors are the mechanical definition-of-done**
+  (`dw-demo-base/references/visual-qa.md`): the `overflowX` / section-gap / stretched-image /
+  placeholder detectors are framed as a blocking pass/fail run before eyeballing, not a checklist
+  the agent may skip.
+- **Design sign-off — taste stays human without blocking automation**
+  (`dw-demo-base/references/orchestrator.md` acceptance criteria; `visual-qa.md` DoD): a stamped,
+  non-blocking sign-off leg that reports SKIP ("awaiting human sign-off") until a sign-off
+  artifact exists, then PASS — so visual taste gets a human decision on the keeper screenshots
+  without a build-blocking pause (the one blocking human gate stays the impact sign-off).
+- **Authoring detector/probe scripts — three silent-false-green traps**
+  (`dw-demo-base/references/visual-qa.md`): Playwright `page.evaluate` passes exactly one arg
+  (pass an options object); PowerShell `ConvertTo-Json` unwraps a single-element array to a scalar
+  (normalise scalar-or-array on the JS side); and a PowerShell local that is a case-variant of a
+  parameter silently aliases it (`$Body`/`$body` — name the local distinctly). A probe run that
+  emits zero probes must never be reported as PASS.
+
 ## [4.11.0]
 
 Folds eight learnings from two 2026-07 demo-build runs (a customer build dispatch and a

README.md

@@ -136,7 +136,7 @@ Browse Dynamicweb source code on GitHub to understand internal APIs, classes, an
 ### Demos (Presales)
 
 **[dw-demo-base](skills/dw-demo-base/SKILL.md)**
-Foundation skill for all demos. Scaffolds the dw10-suite host, wires the Backend MCP and two-layer localhost TLS bypass, installs Playwright MCP, and drops the customisations and customer-context guardrails. Use this first. Also owns the **orchestrator abstraction** ([references/orchestrator.md](skills/dw-demo-base/references/orchestrator.md)) — how a build is driven, GSD primary or the native `/demo:*` command set. Owns the **hosted/cloud fork** ([references/online-mode.md](skills/dw-demo-base/references/online-mode.md)) — building on an install reached only by URL + Admin API key — and the **publish path** ([references/publish-to-hosted.md](skills/dw-demo-base/references/publish-to-hosted.md)) — migrating a locally-built demo onto one.
+Foundation skill for all demos. Scaffolds the dw10-suite host, wires the Backend MCP and two-layer localhost TLS bypass, installs Playwright MCP, and drops the customisations and customer-context guardrails. Use this first. Also owns the **orchestrator abstraction** ([references/orchestrator.md](skills/dw-demo-base/references/orchestrator.md)) — how a build is driven, GSD primary or the native `/demo:*` command set. Owns the **hosted/cloud fork** ([references/online-mode.md](skills/dw-demo-base/references/online-mode.md)) — building on an install reached only by URL + Admin API key — and the **publish path** ([references/publish-to-hosted.md](skills/dw-demo-base/references/publish-to-hosted.md)) — migrating a locally-built demo onto one. Owns the **visual-QA design gate** ([references/visual-qa.md](skills/dw-demo-base/references/visual-qa.md)) — the mechanical definition-of-done (overflow, section-gap, image-band-height, PLP row-content detectors) plus a human taste sign-off.
 
 **[dw-demo-pim](skills/dw-demo-pim/SKILL.md)**
 PIM modelling from a blank DB — product data built from scratch via MCP. Use after `dw-demo-base`.

skills/dw-demo-base/references/orchestrator.md

@@ -264,7 +264,20 @@ native single pass produced it. Per phase:
   the cart; the re-skin reads as the customer's brand; the `CUSTOMISATIONS.md` ledger accounts
   for every custom-code row.
 - **Polish** — no broken links on the storyline path; no placeholder/lorem content on visited
-  pages; the demo runs end-to-end in one pass without a dead end.
+  pages; the demo runs end-to-end in one pass without a dead end; the mechanical visual-QA gate
+  passes on every demo-critical page (see `references/visual-qa.md` "Definition of done") **and**
+  the design has a human taste sign-off.
+
+**Design sign-off — taste stays human without blocking automation.** Mechanical asserts prove
+structure (image-band caps, PLP row-presence + content, no overflow/gaps — `references/visual-qa.md`);
+they cannot judge visual hierarchy or brand fit, so an all-green mechanical run can still ship a
+page that reads wrong. Reserve that judgement as a **stamped, non-blocking** leg rather than a
+human pause: the design sign-off check reports **SKIP ("awaiting human sign-off")** until a
+sign-off artifact (e.g. `home/<slug>/design-signoff.json` — `{ signed_off_by, ts, notes }`,
+written by an approve-design step) exists, then **PASS**. A SKIP is stamped, never a FAIL, so it
+records "taste not yet reviewed" without failing the build or forcing an execution pause — the one
+*blocking* human gate remains the impact sign-off. The keeper screenshots at both breakpoints are
+the artifact the human signs off on.
 
 A demo that needs different criteria edits this list in its own roadmap; the orchestrator reads
 the project's copy, so both orchestrators stay in agreement.