groundwork-method 0.0.1 → 0.11.0

package/src/generators/system-test-runner/files/tests/system/test_system.py.template

@@ -0,0 +1,158 @@
+"""Real, discovery-driven system tests. Parametrized over every APP service
+found in the workspace docker-compose.yml (see conftest.services_manifest).
+
+FAIL LOUD: the span tests are gated by GROUNDWORK_REQUIRE_TRACES=1. When that
+flag is set (CI, `./dev test integration`), an unreachable backend or a
+missing span is a FAILURE, not a skip.
+"""
+
+import os
+import time
+import uuid
+
+import httpx
+import pytest
+
+from conftest import JAEGER_URL, _base_url, _discover_services
+
+REQUIRE_TRACES = os.environ.get("GROUNDWORK_REQUIRE_TRACES") == "1"
+# BatchSpanProcessor flushes ~every 5s; give spans time to land.
+EXPORT_TIMEOUT_S = 30
+
+# Build params at import time so pytest can show one case per service. An empty
+# workspace yields zero params (and the suite is a no-op, which is correct).
+_SERVICES = _discover_services()
+_PARAMS = [pytest.param(s, id=s["name"]) for s in _SERVICES]
+
+
+def _fetch_trace(trace_id: str) -> dict | None:
+    deadline = time.time() + EXPORT_TIMEOUT_S
+    while time.time() < deadline:
+        resp = httpx.get(f"{JAEGER_URL}/api/traces/{trace_id}", timeout=3.0)
+        if resp.status_code == 200 and resp.json().get("data"):
+            return resp.json()["data"][0]
+        time.sleep(1)
+    return None
+
+
+@pytest.mark.parametrize("svc", _PARAMS)
+def test_every_service_is_healthy(cluster, svc):
+    """Each discovered service answers its health endpoint. Synchronous on
+    purpose (like the trace probes below): a plain GET needs no event loop, and
+    avoiding an async fixture keeps the suite robust across pytest-asyncio /
+    Python versions."""
+    if svc["host_port"] is None:
+        pytest.skip(f"{svc['name']} has no published host port")
+    url = f"{_base_url(svc)}{svc['health_path']}"
+    resp = httpx.get(url, timeout=5.0)
+    assert resp.status_code == 200, f"{url} -> {resp.status_code}"
+    data = resp.json()
+    if svc["type"] == "go":
+        assert data.get("status") == "ok", f"{svc['name']} status: {data}"
+        assert data.get("checks", {}).get("db") == "ok", f"{svc['name']} db: {data}"
+    else:
+        # Python FastAPI returns {"status": "alive"}; Next returns its own shape.
+        assert data.get("status") in {"ok", "alive", "ready", "healthy"}, f"{svc['name']}: {data}"
+
+
+@pytest.mark.parametrize("svc", _PARAMS)
+def test_instrumented_get_exports_span(cluster, svc):
+    """A traced GET to an instrumented route produces a span that reaches jaeger.
+
+    Go and Python both export spans over OTLP: Go via otel.go, Python via the
+    FastAPI instrumentation wired in adapters/telemetry.py. Next.js server-side
+    tracing is unverified through this harness (no domain GET route to probe),
+    so it xfails here.
+    """
+    if svc["type"] not in ("go", "python"):
+        pytest.xfail(f"{svc['type']} trace export not verified through this harness (TODO)")
+    if svc["host_port"] is None:
+        pytest.skip(f"{svc['name']} has no published host port")
+
+    trace_id = uuid.uuid4().hex
+    span_id = uuid.uuid4().hex[:16]
+    # The trailing -01 (sampled) flag is load-bearing: ParentBased(AlwaysSample)
+    # inherits it. -00 exports nothing.
+    traceparent = f"00-{trace_id}-{span_id}-01"
+    # /health is excluded from tracing by the otelhttp middleware; use a real
+    # route. Default is per-service-type (Go /api/v1/entities, Python /examples);
+    # TRACE_PROBE_PATH overrides for ad-hoc runs.
+    probe = os.environ.get("TRACE_PROBE_PATH", svc["probe_path"])
+
+    # Warm up: a just-booted service can serve liveness before its DB-backed routes
+    # are ready (e.g. a schema migration is still settling), so the first requests
+    # may transiently 5xx. Retry until the route is ready so this asserts span
+    # export, not startup ordering (test_every_service_is_healthy covers liveness).
+    resp = None
+    for attempt in range(8):
+        resp = httpx.get(
+            f"{_base_url(svc)}{probe}",
+            headers={"traceparent": traceparent},
+            timeout=5.0,
+        )
+        if resp.status_code == 200:
+            break
+        time.sleep(2)
+    assert resp.status_code == 200, f"probe failed after warmup retries: {resp.status_code}"
+
+    trace = _fetch_trace(trace_id)
+    if trace is None:
+        msg = (
+            f"no span with trace_id={trace_id} reached jaeger within "
+            f"{EXPORT_TIMEOUT_S}s — the OTLP export pipeline is broken"
+        )
+        if REQUIRE_TRACES:
+            pytest.fail(msg)
+        pytest.skip(msg)
+
+    services = {p["serviceName"] for p in trace["processes"].values()}
+    assert svc["otel_name"] in services, (
+        f"expected span from '{svc['otel_name']}', got {services}"
+    )
+    assert trace["spans"], "trace arrived but contains no spans"
+
+
+@pytest.mark.parametrize("svc", _PARAMS)
+def test_trace_context_propagates_unchanged(cluster, svc):
+    """The service continues the incoming trace id rather than starting a new one."""
+    if svc["type"] not in ("go", "python"):
+        pytest.xfail(f"{svc['type']} trace export not verified through this harness (TODO)")
+    if svc["host_port"] is None:
+        pytest.skip(f"{svc['name']} has no published host port")
+
+    trace_id = uuid.uuid4().hex
+    span_id = uuid.uuid4().hex[:16]
+    traceparent = f"00-{trace_id}-{span_id}-01"
+    probe = os.environ.get("TRACE_PROBE_PATH", svc["probe_path"])
+
+    httpx.get(
+        f"{_base_url(svc)}{probe}",
+        headers={"traceparent": traceparent},
+        timeout=5.0,
+    )
+    trace = _fetch_trace(trace_id)
+    if trace is None:
+        msg = "injected trace context was not propagated/exported"
+        if REQUIRE_TRACES:
+            pytest.fail(msg)
+        pytest.skip(msg)
+    # Compare numerically so leading-zero normalisation doesn't cause a false fail.
+    assert int(trace["traceID"], 16) == int(trace_id, 16)
+
+
+@pytest.mark.skip(reason="real CRUD lands in Phase 4")
+@pytest.mark.asyncio
+@pytest.mark.parametrize("svc", _PARAMS)
+async def test_crud_round_trip(cluster, api_client: httpx.AsyncClient, svc):
+    """POST then GET an entity and assert the round-trip through the real DB."""
+    if svc["type"] != "go":
+        pytest.skip("CRUD round-trip targets Go services for now")
+    base = _base_url(svc)
+    payload = {"name": "phase0-roundtrip"}
+    created = await api_client.post(f"{base}/api/v1/entities", json=payload, timeout=5.0)
+    assert created.status_code in (200, 201), created.text
+    entity_id = created.json().get("id")
+    assert entity_id, "POST did not return an id"
+    fetched = await api_client.get(f"{base}/api/v1/entities/{entity_id}", timeout=5.0)
+    assert fetched.status_code == 200
+    assert fetched.json().get("name") == payload["name"]

package/src/generators/system-test-runner/files/tests/system/test_token_conformance.py.template

@@ -0,0 +1,206 @@
+<% if (!surfaces) { -%>
+"""Token-conformance gate — Tier 1 of the visual verification loop.
+
+The deterministic answer to "did the polish actually land?" A behavioural test
+passes while the atmosphere has silently degraded to a flat default — the build
+dropped the design system's surface treatment, or the projected tokens never
+reached the page. This gate reads computed styles and asserts the opposite:
+the atmosphere tokens resolve, the elevation is a multi-layer stack (not one
+default drop shadow), and any surface treatment in the DOM renders with its
+backdrop blur and layered shadow rather than collapsing to a framework default.
+
+It is deliberately structural, not aesthetic: it cannot judge taste (that is the
+designer's spec-conformance pass), but it makes "the tokens are applied" a fact,
+not an opinion. Skips cleanly when no frontend service is discovered.
+"""
+
+import json
+import pathlib
+
+from playwright.sync_api import Page
+
+# Atmosphere tokens the nextjs-app generator projects into brand.css from the
+# design system's visual block. Their presence proves the projection landed.
+_PROBE = """
+() => {
+  const root = getComputedStyle(document.documentElement);
+  const tok = (n) => (root.getPropertyValue(n) || '').trim();
+  const countLayers = (s) => {
+    s = (s || '').trim();
+    if (!s || s === 'none') return 0;
+    let depth = 0, n = 1;
+    for (const ch of s) {
+      if (ch === '(') depth++;
+      else if (ch === ')') depth--;
+      else if (ch === ',' && depth === 0) n++;
+    }
+    return n;
+  };
+  const surfaces = [];
+  for (const el of document.querySelectorAll('.surface-glass, .surface-elevated, .surface-hero')) {
+    const cs = getComputedStyle(el);
+    const bf = (cs.backdropFilter || cs.webkitBackdropFilter || '').trim();
+    surfaces.push({
+      cls: el.className,
+      hasBlur: /blur\\(/.test(bf),
+      shadowLayers: countLayers(cs.boxShadow),
+    });
+  }
+  return {
+    shadowMid: tok('--gw-shadow-mid'),
+    shadowMidLayers: countLayers(tok('--gw-shadow-mid')),
+    blurStandard: tok('--gw-blur-standard'),
+    surfaces,
+  };
+}
+"""
+
+
+def _load_routes() -> tuple[str, ...]:
+    manifest = pathlib.Path("tests/system/routes.json")
+    if manifest.exists():
+        try:
+            routes = json.loads(manifest.read_text())
+            if isinstance(routes, list) and routes:
+                return tuple(routes)
+        except Exception:  # noqa: BLE001 — a malformed manifest falls back to root
+            pass
+    return ("/",)
+
+
+ROUTES = _load_routes()
+
+
+def _assert_token_conformance(page: Page, surface_slug: str, base_url: str | None) -> None:
+    for route in ROUTES:
+        target = (base_url.rstrip("/") + route) if base_url else route
+        page.goto(target, wait_until="load")
+        page.wait_for_load_state("networkidle")
+        r = page.evaluate(_PROBE)
+
+        # The atmosphere layer projected into :root.
+        assert r["shadowMid"], (
+            f"{surface_slug} {route}: --gw-shadow-mid is undefined — the brand.css "
+            f"projection did not reach the page (atmosphere tokens missing)."
+        )
+        assert r["blurStandard"], (
+            f"{surface_slug} {route}: --gw-blur-standard is undefined — blur tokens "
+            f"did not project."
+        )
+        assert r["shadowMidLayers"] >= 2, (
+            f"{surface_slug} {route}: --gw-shadow-mid is a single-layer shadow "
+            f"({r['shadowMidLayers']} layer) — the multi-layer elevation stack "
+            f"degraded to a default drop shadow."
+        )
+
+        # Any surface treatment in the DOM rendered its atmosphere, not a flat default.
+        for s in r["surfaces"]:
+            assert s["hasBlur"], (
+                f"{surface_slug} {route}: '{s['cls']}' rendered with no backdrop "
+                f"blur — the glass treatment was stripped to a flat fill."
+            )
+            assert s["shadowLayers"] >= 2, (
+                f"{surface_slug} {route}: '{s['cls']}' rendered with "
+                f"{s['shadowLayers']} shadow layer(s) — the elevation stack was lost."
+            )
+
+
+def test_frontend_token_conformance(cluster, frontend_base_url, page: Page):
+    _assert_token_conformance(page, "frontend", frontend_base_url)
+<% } else { -%>
+"""Token-conformance gate, one test per graphical surface — Tier 1 of the visual loop.
+
+The deterministic answer to "did the polish actually land?" A behavioural test
+passes while the atmosphere has silently degraded to a flat default. This gate
+reads computed styles and asserts the atmosphere tokens resolve, the elevation is
+a multi-layer stack, and any surface treatment in the DOM renders with its
+backdrop blur and layered shadow rather than a framework default. Structural, not
+aesthetic — taste is the designer's spec-conformance pass. Skips cleanly when a
+surface is not reachable.
+"""
+
+import json
+import pathlib
+
+from playwright.sync_api import Page
+
+_PROBE = """
+() => {
+  const root = getComputedStyle(document.documentElement);
+  const tok = (n) => (root.getPropertyValue(n) || '').trim();
+  const countLayers = (s) => {
+    s = (s || '').trim();
+    if (!s || s === 'none') return 0;
+    let depth = 0, n = 1;
+    for (const ch of s) {
+      if (ch === '(') depth++;
+      else if (ch === ')') depth--;
+      else if (ch === ',' && depth === 0) n++;
+    }
+    return n;
+  };
+  const surfaces = [];
+  for (const el of document.querySelectorAll('.surface-glass, .surface-elevated, .surface-hero')) {
+    const cs = getComputedStyle(el);
+    const bf = (cs.backdropFilter || cs.webkitBackdropFilter || '').trim();
+    surfaces.push({
+      cls: el.className,
+      hasBlur: /blur\\(/.test(bf),
+      shadowLayers: countLayers(cs.boxShadow),
+    });
+  }
+  return {
+    shadowMid: tok('--gw-shadow-mid'),
+    shadowMidLayers: countLayers(tok('--gw-shadow-mid')),
+    blurStandard: tok('--gw-blur-standard'),
+    surfaces,
+  };
+}
+"""
+
+
+def _load_routes() -> tuple[str, ...]:
+    manifest = pathlib.Path("tests/system/routes.json")
+    if manifest.exists():
+        try:
+            routes = json.loads(manifest.read_text())
+            if isinstance(routes, list) and routes:
+                return tuple(routes)
+        except Exception:  # noqa: BLE001 — a malformed manifest falls back to root
+            pass
+    return ("/",)
+
+
+ROUTES = _load_routes()
+
+
+def _assert_token_conformance(page: Page, surface_slug: str) -> None:
+    for route in ROUTES:
+        page.goto(route, wait_until="load")
+        page.wait_for_load_state("networkidle")
+        r = page.evaluate(_PROBE)
+
+        assert r["shadowMid"], (
+            f"{surface_slug} {route}: --gw-shadow-mid is undefined — the brand.css "
+            f"projection did not reach the page."
+        )
+        assert r["blurStandard"], (
+            f"{surface_slug} {route}: --gw-blur-standard is undefined."
+        )
+        assert r["shadowMidLayers"] >= 2, (
+            f"{surface_slug} {route}: --gw-shadow-mid degraded to a single-layer "
+            f"shadow ({r['shadowMidLayers']} layer)."
+        )
+        for s in r["surfaces"]:
+            assert s["hasBlur"], (
+                f"{surface_slug} {route}: '{s['cls']}' rendered with no backdrop blur."
+            )
+            assert s["shadowLayers"] >= 2, (
+                f"{surface_slug} {route}: '{s['cls']}' rendered with "
+                f"{s['shadowLayers']} shadow layer(s) — elevation stack lost."
+            )
+<% graphicalSurfaces.forEach((s) => { %>
+
+def test_<%= s.ident %>_token_conformance(cluster, <%= s.ident %>_page: Page):
+    _assert_token_conformance(<%= s.ident %>_page, "<%= s.slug %>")
+<% }) %><% } -%>

package/src/generators/system-test-runner/files/tests/system/test_visual_regression.py.template

@@ -0,0 +1,104 @@
+"""Visual regression gate — Tier 1 of the visual verification loop, OPT-IN.
+
+Screenshot-baseline diffing catches *unintended* visual change against a known-good
+baseline. It is off by default (decision D8): it carries real baseline-management and
+flakiness cost, and it does nothing for a screen's *first* render — that is what the
+render-smoke, a11y, and geometry gates plus the agent's own inspection cover. Turn it
+on only once a surface is visually stable and worth pinning.
+
+Enable: set GROUNDWORK_VISUAL_REGRESSION=1. Baselines live in
+tests/system/visual-baselines/<surface>/<route>.png and are committed to the repo.
+Update protocol: review the diff, then re-run with GROUNDWORK_VISUAL_REGRESSION=update
+to overwrite the baseline deliberately — never auto-update in CI.
+
+Determinism note: when enabled the gate pins the viewport, disables animations, and
+masks nothing by default; add per-project masks for dynamic regions (timestamps,
+avatars) before trusting it. Requires Pillow for the pixel diff; skips if absent.
+"""
+
+import json
+import os
+import pathlib
+
+import pytest
+from playwright.sync_api import Page
+
+_MODE = os.environ.get("GROUNDWORK_VISUAL_REGRESSION", "")
+_BASELINE_DIR = pathlib.Path("tests/system/visual-baselines")
+# Fraction of differing pixels tolerated before a route is considered changed.
+_DIFF_THRESHOLD = 0.01
+DESKTOP = (1280, 800)
+
+
+def _load_routes() -> tuple[str, ...]:
+    manifest = pathlib.Path("tests/system/routes.json")
+    if manifest.exists():
+        try:
+            routes = json.loads(manifest.read_text())
+            if isinstance(routes, list) and routes:
+                return tuple(routes)
+        except Exception:  # noqa: BLE001 — a malformed manifest falls back to root
+            pass
+    return ("/",)
+
+
+ROUTES = _load_routes()
+
+
+def _diff_fraction(a_bytes: bytes, b_bytes: bytes) -> float:
+    from io import BytesIO
+
+    from PIL import Image, ImageChops
+
+    a = Image.open(BytesIO(a_bytes)).convert("RGB")
+    b = Image.open(BytesIO(b_bytes)).convert("RGB")
+    if a.size != b.size:
+        return 1.0
+    diff = ImageChops.difference(a, b)
+    bbox = diff.getbbox()
+    if bbox is None:
+        return 0.0
+    changed = sum(1 for px in diff.crop(bbox).getdata() if any(px))
+    return changed / float(a.size[0] * a.size[1])
+
+
+def _visual_regression(page: Page, surface_slug: str, base_url: str | None) -> None:
+    if not _MODE:
+        pytest.skip("visual regression is opt-in; set GROUNDWORK_VISUAL_REGRESSION=1")
+    try:
+        import PIL  # noqa: F401
+    except ImportError:
+        pytest.skip("visual regression needs Pillow (pip install Pillow)")
+
+    page.set_viewport_size({"width": DESKTOP[0], "height": DESKTOP[1]})
+    out_dir = _BASELINE_DIR / surface_slug
+    for route in ROUTES:
+        target = (base_url.rstrip("/") + route) if base_url else route
+        page.goto(target, wait_until="load")
+        page.wait_for_load_state("networkidle")
+        shot = page.screenshot(animations="disabled", full_page=True)
+
+        slug = route.strip("/").replace("/", "_") or "root"
+        baseline = out_dir / f"{slug}.png"
+        if _MODE == "update" or not baseline.exists():
+            out_dir.mkdir(parents=True, exist_ok=True)
+            baseline.write_bytes(shot)
+            if _MODE != "update":
+                pytest.skip(f"no baseline for {surface_slug} {route}; wrote one — review and commit it")
+            continue
+
+        frac = _diff_fraction(baseline.read_bytes(), shot)
+        assert frac <= _DIFF_THRESHOLD, (
+            f"{surface_slug} {route} changed visually: {frac:.1%} of pixels differ "
+            f"from the baseline (threshold {_DIFF_THRESHOLD:.0%}). Review the change; "
+            f"re-run with GROUNDWORK_VISUAL_REGRESSION=update to accept it."
+        )
+<% if (!surfaces) { -%>
+
+def test_frontend_visual_regression(cluster, frontend_base_url, page: Page):
+    _visual_regression(page, "frontend", frontend_base_url)
+<% } else { -%><% graphicalSurfaces.forEach((s) => { %>
+
+def test_<%= s.ident %>_visual_regression(cluster, <%= s.ident %>_page: Page):
+    _visual_regression(<%= s.ident %>_page, "<%= s.slug %>", None)
+<% }) %><% } -%>

package/src/generators/system-test-runner/generator.ts

@@ -0,0 +1,196 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+
+/** One surface from the registry (`.groundwork/surfaces.json`). The slug is the
+ *  join key everywhere — ledger cells, fixture map keys, generated fixture
+ *  names. `medium` is the registry's `testMedium`; `reach` is an optional
+ *  static base URL (playwright / protocol-client), launch command
+ *  (subprocess-cli), or test-harness command (flutter-integration /
+ *  playwright-electron) — omitted, URL mediums are discovered at test time
+ *  from the docker-compose service named after the slug, and harness mediums
+ *  resolve to `npx nx run <slug>:<target>` when services/<slug> exists. */
+export interface SurfaceSpec {
+  slug: string;
+  medium: string;
+  reach?: string;
+}
+
+export interface SystemTestRunnerGeneratorSchema {
+  projectPrefix?: string;
+  /** Deprecated single-surface alias — `surfaces` supersedes it. */
+  interfaceMedium?: 'graphical-ui' | 'cli' | 'agentic-protocol';
+  /** JSON array of SurfaceSpec (string form when invoked from the CLI). */
+  surfaces?: string | SurfaceSpec[];
+}
+
+/** Parsed spec plus the python-identifier form of the slug, for fixture names. */
+interface SurfaceTemplateSpec extends SurfaceSpec {
+  ident: string;
+}
+
+function parseSurfaces(
+  raw: string | SurfaceSpec[] | undefined
+): SurfaceTemplateSpec[] | null {
+  if (raw === undefined || raw === null || raw === '') {
+    return null;
+  }
+  let specs: unknown;
+  if (typeof raw === 'string') {
+    try {
+      specs = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(`--surfaces is not valid JSON: ${(e as Error).message}`);
+    }
+  } else {
+    specs = raw;
+  }
+  if (!Array.isArray(specs) || specs.length === 0) {
+    throw new Error(
+      '--surfaces must be a non-empty JSON array of {slug, medium, reach?} objects'
+    );
+  }
+  for (const spec of specs as SurfaceSpec[]) {
+    if (
+      !spec ||
+      typeof spec.slug !== 'string' ||
+      spec.slug.length === 0 ||
+      typeof spec.medium !== 'string' ||
+      spec.medium.length === 0
+    ) {
+      throw new Error(
+        `every --surfaces entry needs a slug and a medium: ${JSON.stringify(spec)}`
+      );
+    }
+  }
+  return (specs as SurfaceSpec[]).map((s) => ({
+    ...s,
+    ident: s.slug.replace(/-/g, '_'),
+  }));
+}
+
+/** A fail-closed pytest stub for a graphical surface with no runnable UI check.
+ *  It fails (never skips) so the surface's UI proof is an honest red until a
+ *  platform check is implemented per NATIVE-CHECK-CONTRACT.md. Deleting it to go
+ *  green is the silent-skip this exists to prevent. */
+function uiCheckPlaceholder(s: SurfaceTemplateSpec): string {
+  return `import pytest
+
+# AUTO-GENERATED fail-closed placeholder — do not delete to go green.
+# Surface "${s.slug}" (test medium "${s.medium}") is a surface GroundWork has no
+# UI check runner for. A milestone cannot be proven on a surface nothing checks,
+# so this placeholder FAILS until a platform UI check is implemented for it per
+# src/generators/system-test-runner/NATIVE-CHECK-CONTRACT.md (render,
+# navigation / no dead ends, the named states, design-system token match).
+
+
+def test_${s.ident}_ui_check_not_implemented():
+    pytest.fail(
+        "No UI check runner for surface '${s.slug}' (medium '${s.medium}'). "
+        "Implement a platform UI check per "
+        "system-test-runner/NATIVE-CHECK-CONTRACT.md, then replace this "
+        "fail-closed placeholder. A graphical surface must not ship unverified."
+    )
+`;
+}
+
+export async function systemTestRunnerGenerator(
+  tree: Tree,
+  options: SystemTestRunnerGeneratorSchema
+) {
+  const projectPrefix = options.projectPrefix || 'groundwork';
+  const interfaceMedium = options.interfaceMedium || 'graphical-ui';
+  // Registry mode: `surfaces` carries the full set of test mediums and wins
+  // over the deprecated single-medium alias when both are given.
+  const surfaces = parseSurfaces(options.surfaces);
+
+  const graphicalSurfaces = (surfaces ?? []).filter((s) => s.medium === 'playwright');
+  const cliSurfaces = (surfaces ?? []).filter((s) => s.medium === 'subprocess-cli');
+  const protocolSurfaces = (surfaces ?? []).filter((s) => s.medium === 'protocol-client');
+  // App-harness mediums: the surface ships its own test harness (Flutter
+  // integration_test / Playwright _electron smoke); the runner fixture drives
+  // it as a subprocess through the app's Nx target.
+  const flutterSurfaces = (surfaces ?? []).filter((s) => s.medium === 'flutter-integration');
+  const electronSurfaces = (surfaces ?? []).filter((s) => s.medium === 'playwright-electron');
+
+  // Every test medium GroundWork knows how to run a check for. A graphical
+  // surface registered with a medium outside this set has no UI check runner —
+  // and a milestone cannot be proven on a surface nothing checks. We refuse to
+  // silently leave it unverified: each such surface gets a fail-closed
+  // placeholder check (below) naming the gap, never a silent no-op.
+  const KNOWN_MEDIA = new Set([
+    'playwright',
+    'subprocess-cli',
+    'protocol-client',
+    'flutter-integration',
+    'playwright-electron',
+  ]);
+  const unsupportedSurfaces = (surfaces ?? []).filter((s) => !KNOWN_MEDIA.has(s.medium));
+
+  // Playwright structure follows graphical surfaces: any playwright surface in
+  // registry mode, the graphical-ui value in single-medium mode. pexpect ships
+  // alongside the subprocess runners so interactive (REPL) CLI flows are testable.
+  const includePlaywright = surfaces
+    ? graphicalSurfaces.length > 0
+    : interfaceMedium === 'graphical-ui';
+  const includePexpect = cliSurfaces.length > 0;
+
+  // Generate files into the workspace root
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'system-test-runner', 'files'),
+    '.',
+    {
+      ...options,
+      projectPrefix,
+      interfaceMedium,
+      surfaces,
+      graphicalSurfaces,
+      cliSurfaces,
+      protocolSurfaces,
+      flutterSurfaces,
+      electronSurfaces,
+      includePlaywright,
+      includePexpect,
+      tmpl: ''
+    }
+  );
+
+  // Playwright structure ships only with a graphical web surface: the
+  // page-object package, the axe-core a11y smoke, and the render-smoke gate
+  // depend on pytest-playwright, which the pyproject template declares only when
+  // includePlaywright is set. Removing the web-specific gates here is correct —
+  // they genuinely cannot run without a web surface. What must never happen is a
+  // graphical surface left with no check at all; the placeholder below closes
+  // that gap fail-closed instead of silently.
+  if (!includePlaywright) {
+    tree.delete('tests/system/pages');
+    tree.delete('tests/system/test_a11y_smoke.py');
+    tree.delete('tests/system/test_render_smoke.py');
+    tree.delete('tests/system/test_layout_geometry.py');
+    tree.delete('tests/system/test_visual_regression.py');
+    tree.delete('tests/system/test_token_conformance.py');
+  }
+
+  // Fail-closed: a graphical surface whose test medium GroundWork cannot run a
+  // check for gets a placeholder that FAILS naming the gap, never a silent skip.
+  // The scaffold still generates and its other tests run; this surface's UI
+  // proof is an honest red until a platform check is implemented per
+  // NATIVE-CHECK-CONTRACT.md — the follow-on that turns it green.
+  for (const s of unsupportedSurfaces) {
+    tree.write(
+      `tests/system/test_${s.ident}_ui_check_missing.py`,
+      uiCheckPlaceholder(s)
+    );
+  }
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'system-test-runner', options as unknown as Record<string, unknown>);
+}
+
+export default systemTestRunnerGenerator;