@momentiq/dark-factory-cli 2.5.0 → 2.6.0

package/skills/verify/producer/playwright-route.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# Reusable Evidence-Gated Validation **playwright (UI) route** producer command
+# (momentiq-ai/dark-factory#193). Generalized from the dark-factory-dashboard
+# dogfood (Cycle 21 PR-4).
+#
+# This is the `command` of the `playwright` route in
+# `.agent-review/config.json:validation.verificationRoutes`. The
+# @momentiq/dark-factory-cli route-runner (`df verify` / `df gate-push`) spawns
+# it with NO shell — the route command is `command.trim().split(/\s+/)` then
+# `spawn(argv[0], argv.slice(1))` — which is why the route command is the single
+# token-pair `bash scripts/verify/playwright-route.sh` and ALL the real work
+# (guards, Playwright, exit mapping) lives here.
+#
+# Exit-code contract (the 0/1/2 route contract):
+#   0 — green: evidence captured, the routed UI surface(s) rendered + asserted.
+#   1 — block: a routed UI surface failed to render/assert, OR a real producer
+#       error (Playwright crashed, a guarded file is dirty). Fail closed.
+#   2 — soft-skip: the producer cannot run HERE (Playwright not installed, or a
+#       required auth storage-state is configured but absent). Mapped by the CLI
+#       to `requiresHumanJudgment` — NOT a pass. We NEVER fabricate evidence.
+#
+# ── CONSUMER REFERENCE FILE — copy into your repo (e.g. scripts/verify/) and
+#    OWN it. Adjust the env knobs at the top to your repo layout. Then arm the
+#    `playwright` route's `command` to `bash <path-to-this-script>` in
+#    .agent-review/config.json. `df skills install verify` does NOT overwrite it.
+#
+# Usage (normally invoked by the route-runner via `df verify --route playwright`):
+#   bash scripts/verify/playwright-route.sh [--commit <ref>]
+
+set -uo pipefail
+
+EXIT_GREEN=0
+EXIT_BLOCK=1
+EXIT_SOFT_SKIP=2
+
+# --- consumer-tunable knobs (env overrides) --------------------------------
+# Directory where your web app + @playwright/test live (Playwright runs there).
+WEB_DIR="${DF_UI_ROUTE_WEB_DIR:-web}"
+# The producer config, relative to WEB_DIR.
+ROUTE_CONFIG="${DF_UI_ROUTE_CONFIG:-playwright.ui-route.config.ts}"
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "${REPO_ROOT}"
+
+# Path of THIS script relative to the repo root — added to the clean-tree guard
+# so a dirty producer (which would run DIFFERENT logic than the committed SHA)
+# fails closed too. Computed dynamically so it works wherever you copy it.
+SCRIPT_ABS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
+SCRIPT_REL="${SCRIPT_ABS#"${REPO_ROOT}/"}"
+
+# --- resolve the SHA under review ------------------------------------------
+# Prefer DF_VERIFY_COMMIT (exported by a route orchestrator that pins the gated
+# commit), then an explicit --commit, then HEAD.
+SHA_REF="${DF_VERIFY_COMMIT:-HEAD}"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --commit) SHA_REF="${2:-HEAD}"; shift 2 ;;
+    --commit=*) SHA_REF="${1#*=}"; shift ;;
+    *) shift ;;
+  esac
+done
+SHA="$(git rev-parse "${SHA_REF}" 2>/dev/null || echo "")"
+if [[ -z "${SHA}" ]]; then
+  echo "[playwright-route] FAIL: could not resolve commit '${SHA_REF}'." >&2
+  exit "${EXIT_BLOCK}"
+fi
+
+# SHA-binding guard: the producer drives a browser against the CHECKED-OUT
+# working tree (HEAD), so it can only honestly attest evidence for HEAD. If
+# asked to produce evidence for a non-HEAD SHA, FAIL CLOSED rather than stamp a
+# passing record whose screenshots actually reflect HEAD.
+HEAD_SHA="$(git rev-parse HEAD 2>/dev/null || echo "")"
+if [[ "${SHA}" != "${HEAD_SHA}" ]]; then
+  echo "[playwright-route] BLOCK: asked to produce evidence for ${SHA:0:12} but HEAD is ${HEAD_SHA:0:12}." >&2
+  echo "[playwright-route] the producer validates the checked-out tree (HEAD) only; refusing to mis-bind evidence. Check out the target SHA and re-run." >&2
+  exit "${EXIT_BLOCK}"
+fi
+
+# Clean-tree guard: the producer screenshots the WORKING TREE, but evidence
+# binds to the committed SHA. If any file that affects either the rendered UI OR
+# the route's execution/evidence contract is dirty or untracked, the capture
+# would attest code that is NOT in ${SHA}. FAIL CLOSED. The guarded set is the
+# UI surface (web/** + *.tsx) AND the route machinery itself (this script + the
+# route config) — a dirty producer runs different logic than the committed SHA.
+GUARDED_PATHS=(
+  "${WEB_DIR}/**" '*.tsx'
+  "${SCRIPT_REL}"
+  '.agent-review/config.json'
+)
+if ! git diff-index --quiet HEAD -- "${GUARDED_PATHS[@]}" 2>/dev/null; then
+  echo "[playwright-route] BLOCK: tracked UI or route-machinery files are dirty (uncommitted changes)." >&2
+  echo "[playwright-route] the producer captures the working tree but evidence binds to ${SHA:0:12}; commit or stash changes under ${WEB_DIR}/**, *.tsx, ${SCRIPT_REL}, or .agent-review/config.json, then re-run." >&2
+  exit "${EXIT_BLOCK}"
+fi
+UNTRACKED_GUARDED="$(git ls-files --others --exclude-standard -- "${GUARDED_PATHS[@]}" 2>/dev/null | head -1 || true)"
+if [[ -n "${UNTRACKED_GUARDED}" ]]; then
+  echo "[playwright-route] BLOCK: untracked UI/route-machinery file(s) present (e.g. ${UNTRACKED_GUARDED}) not in ${SHA:0:12}." >&2
+  echo "[playwright-route] commit or remove untracked files under the guarded set so the capture matches the gated commit, then re-run." >&2
+  exit "${EXIT_BLOCK}"
+fi
+
+echo "[playwright-route] producing UI evidence for ${SHA:0:12} (ref=${SHA_REF}, =HEAD, clean tree)" >&2
+
+# Compute the UI paths this commit actually changed (parent..SHA), restricted to
+# the route's trigger surface (web/** + *.tsx). Handed to the producer so it can
+# FAIL CLOSED when a changed UI path has no mapped capture surface. Excludes
+# deletions (D) — a removed file has no surface to render.
+PARENT="$(git rev-parse "${SHA}^" 2>/dev/null || echo "")"
+if [[ -n "${PARENT}" ]]; then
+  CHANGED_UI_PATHS="$(git diff --name-only --diff-filter=ACMRT "${PARENT}" "${SHA}" -- "${WEB_DIR}/**" '*.tsx' 2>/dev/null || true)"
+else
+  # Root commit — list all tracked UI paths.
+  CHANGED_UI_PATHS="$(git ls-files -- "${WEB_DIR}/**" '*.tsx' 2>/dev/null || true)"
+fi
+export DF_UI_ROUTE_CHANGED_PATHS="${CHANGED_UI_PATHS}"
+
+# Anchor the evidence dir at the REPO ROOT (absolute), because Playwright runs
+# with cwd=${WEB_DIR} — a relative path would land under ${WEB_DIR}.
+OUT_DIR="${REPO_ROOT}/agent-reviews/quality-gates/ui/${SHA}"
+mkdir -p "${OUT_DIR}"
+export DF_UI_ROUTE_SHA="${SHA}"
+export DF_UI_ROUTE_OUT="${OUT_DIR}"
+
+# --- preflight: web tier present + Playwright installed --------------------
+if [[ ! -d "${WEB_DIR}/node_modules/@playwright" ]]; then
+  echo "[playwright-route] SOFT-SKIP: ${WEB_DIR}/ Playwright not installed (run \`cd ${WEB_DIR} && npm ci\`)." >&2
+  echo "[playwright-route] not fabricating evidence — requiresHumanJudgment." >&2
+  exit "${EXIT_SOFT_SKIP}"
+fi
+
+# --- auth storage-state gate (optional) ------------------------------------
+# Public surfaces need no auth. If you configured an auth storage-state
+# (DF_UI_ROUTE_STORAGE_STATE) but the file is absent (e.g. a cloud sandbox where
+# your auth harness could not mint it), SOFT-SKIP rather than pass — we will not
+# produce a protected-surface artifact we cannot legitimately authenticate.
+if [[ -n "${DF_UI_ROUTE_STORAGE_STATE:-}" && ! -f "${DF_UI_ROUTE_STORAGE_STATE}" ]]; then
+  echo "[playwright-route] SOFT-SKIP: DF_UI_ROUTE_STORAGE_STATE=${DF_UI_ROUTE_STORAGE_STATE} is set but the file is absent." >&2
+  echo "[playwright-route] cannot authenticate the configured session; not fabricating evidence (requiresHumanJudgment)." >&2
+  exit "${EXIT_SOFT_SKIP}"
+fi
+
+# --- run the producer -------------------------------------------------------
+LOG_FILE="$(mktemp -t df-playwright-route.XXXXXX)"
+trap 'rm -f "${LOG_FILE}"' EXIT
+
+set +e
+( cd "${WEB_DIR}" && npx playwright test --config "${ROUTE_CONFIG}" ) \
+  >"${LOG_FILE}" 2>&1
+RC=$?
+set -e 2>/dev/null || true
+
+# Surface the producer output (bounded) for the gate log / critic.
+tail -n 120 "${LOG_FILE}" >&2 || true
+
+if [[ ${RC} -eq 0 ]]; then
+  echo "[playwright-route] OK — evidence in ${OUT_DIR}" >&2
+  exit "${EXIT_GREEN}"
+fi
+
+echo "[playwright-route] BLOCK: producer failed (exit ${RC}) — see output above." >&2
+exit "${EXIT_BLOCK}"

package/skills/verify/producer/playwright.ui-route.config.ts

@@ -0,0 +1,111 @@
+import { defineConfig, devices } from "@playwright/test";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Reusable Playwright config for the Evidence-Gated Validation **playwright
+ * (UI) route producer** (momentiq-ai/dark-factory#193). Generalized from the
+ * dark-factory-dashboard dogfood (Cycle 21 PR-4; ADR 2026-06).
+ *
+ * Kept SEPARATE from your broad e2e config so the route producer is a single,
+ * fast, deterministic capture:
+ *   - one chromium project, the producer spec only.
+ *   - no retries (a flaky retry could mask a genuinely-failing UI surface).
+ *   - an OPTIONAL authenticated storage-state (public surfaces need none).
+ *   - an OPTIONAL local preview `webServer` (the SHA under review) for the
+ *     no-auth dogfood path; set `PLAYWRIGHT_TEST_BASE_URL` to point at a
+ *     deployed preview of the SHA instead.
+ *
+ * This config is invoked by `playwright-route.sh`, which is the route's
+ * `command` in `.agent-review/config.json`.
+ *
+ * ── CONSUMER REFERENCE FILE — copy into your repo (next to the producer spec)
+ *    and OWN it. Adjust `testDir`, the `webServer.command`, and the env knobs
+ *    to your repo's layout. `df skills install verify` does NOT overwrite it.
+ *
+ * NEVER set a routine pre-push bypass to get around a failing producer — a
+ * failing/absent capture MUST block the route (that is the feature).
+ */
+
+// Auth is OPTIONAL and consumer-supplied. Mint an authenticated Playwright
+// storageState JSON with YOUR auth (Clerk/Auth0/bot login/etc.) and point
+// DF_UI_ROUTE_STORAGE_STATE at it for protected surfaces. Public surfaces need
+// none — when the file is absent we run unauthenticated rather than fail.
+//
+// The default path is anchored to `process.cwd()` — NOT `__dirname` or
+// `import.meta.url`. Playwright may load this config as CJS or ESM depending on
+// the consumer's `"type"` + Playwright version: `__dirname` is undefined under
+// ESM and `import.meta` is invalid under CJS, so either module-global would
+// crash the producer for half of consumers before it could even soft-skip. The
+// route script runs Playwright with `cwd` = the web dir (where this config
+// lives), so cwd-relative resolves to `<web>/.auth/storage-state.json` and
+// works in both. Gitignore **/.auth/.
+const STORAGE_STATE_PATH =
+  process.env.DF_UI_ROUTE_STORAGE_STATE ||
+  resolve(process.cwd(), ".auth/storage-state.json");
+const storageState = existsSync(STORAGE_STATE_PATH) ? STORAGE_STATE_PATH : undefined;
+
+// Local preview port for the SHA-under-review server. Overridable via
+// DF_UI_ROUTE_PORT to avoid collisions with other local services.
+const PREVIEW_PORT = process.env.DF_UI_ROUTE_PORT || "3217";
+const BASE_URL =
+  process.env.PLAYWRIGHT_TEST_BASE_URL?.replace(/\/$/, "") ||
+  `http://localhost:${PREVIEW_PORT}`;
+
+// Only stand up the local preview server when we are NOT pointed at a remote
+// deployed surface. (A remote base URL means the SHA is already served.)
+const usingLocalPreview =
+  !process.env.PLAYWRIGHT_TEST_BASE_URL ||
+  /^https?:\/\/localhost(:|\/|$)/.test(process.env.PLAYWRIGHT_TEST_BASE_URL);
+
+// The command that serves the SHA under review for the local-preview path.
+// Default `npm run dev`; override via DF_UI_ROUTE_DEV_CMD for your stack.
+const DEV_CMD = process.env.DF_UI_ROUTE_DEV_CMD || "npm run dev";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  // Only the route producer — not your broad e2e suite.
+  testMatch: /ui-route\.producer\.spec\.ts$/,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  // The producer must be deterministic; no flaky retries that could mask a
+  // genuinely-failing UI surface behind a lucky re-run.
+  retries: 0,
+  workers: 1,
+  timeout: 90 * 1000,
+  expect: { timeout: 15 * 1000 },
+  reporter: [["list"]],
+
+  use: {
+    baseURL: BASE_URL,
+    // Authenticate ONLY when a storage-state file is present (protected
+    // surfaces). Public surfaces ignore it.
+    ...(storageState ? { storageState } : {}),
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+    ignoreHTTPSErrors: true,
+    actionTimeout: 15 * 1000,
+    navigationTimeout: 30 * 1000,
+  },
+
+  projects: [
+    {
+      name: "ui-route-producer",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+
+  webServer: usingLocalPreview
+    ? {
+        // Serve the SHA under review. Set the port via the PORT env var (the
+        // common convention); adjust DEV_CMD if your dev server differs.
+        command: DEV_CMD,
+        url: BASE_URL,
+        reuseExistingServer: !process.env.CI,
+        timeout: 120 * 1000,
+        env: {
+          PORT: PREVIEW_PORT,
+        },
+      }
+    : undefined,
+});

package/skills/verify/producer/ui-route.producer.spec.ts

@@ -0,0 +1,281 @@
+/**
+ * Reusable **playwright (UI) verification-route producer** (momentiq-ai/
+ * dark-factory#193).
+ *
+ * Generalized from the dark-factory-dashboard dogfood (Cycle 21 EC2/EC8, ADR
+ * 2026-06). This is the `playwright` route's producer: for every UI surface
+ * armed by the change under review it captures the required floor of the SOTA
+ * UI-grounding triad:
+ *
+ *   (1) an **ARIA snapshot** (Playwright `ariaSnapshot()` — the accessibility
+ *       tree, a structural, tamper-resistant assertion that the surface renders
+ *       its expected landmark/heading/role structure) — ALWAYS produced, and
+ *   (2) an **after screenshot** at the SHA under review — ALWAYS produced; plus
+ *       an optional **before screenshot** baseline (completing the before/after
+ *       pair) ONLY when `DF_UI_ROUTE_BEFORE_BASE_URL` is set. A missing baseline
+ *       never fails the route.
+ *
+ * The **optional independent VLM check** (the triad's third leg) is DEFERRED in
+ * v1: the ARIA + after capture is the required floor; the VLM leg is additive
+ * corroboration gated behind a provider/cost decision. The hook is
+ * `runOptionalVlmCheck()` below — a no-op unless `DF_UI_ROUTE_VLM=1` AND a
+ * provider is wired, and it can only ADD a finding, never relax the floor.
+ *
+ * ## Fail-closed coverage
+ *
+ * A `web/**`/`*.tsx` change ARMS the route, but the producer maps each *changed*
+ * UI path to a capture surface; a changed product-UI path with NO mapped surface
+ * BLOCKS the route (the `ui-route-coverage` test below). This is the difference
+ * between an evidence gate and a false-positive generator — a `*.tsx` change
+ * cannot be satisfied by rendering only an unaffected surface. The mapping logic
+ * lives in the unit-tested `coverage.ts`.
+ *
+ * ## Auth (consumer-supplied storage-state — NOT vendor-coupled)
+ *
+ * Public surfaces need no auth. For PROTECTED surfaces, supply an authenticated
+ * Playwright `storageState` JSON and point `DF_UI_ROUTE_STORAGE_STATE` at it
+ * (see `playwright.ui-route.config.ts`). How you mint that session (Clerk, Auth0,
+ * a bot login, a long-lived test cookie) is YOUR repo's concern — the producer
+ * only consumes the storage-state. v1 ships a single public surface so it works
+ * zero-auth out of the box; add protected surfaces + storage-state as needed.
+ *
+ * ## Evidence shape
+ *
+ * Artifacts land under `DF_UI_ROUTE_OUT` (default
+ * `agent-reviews/quality-gates/ui/<sha>/`), one subdir per surface:
+ *   <surface-slug>/aria.snapshot.txt  — the ARIA tree (floor)
+ *   <surface-slug>/after.png          — screenshot at the gated SHA (floor)
+ *   <surface-slug>/before.png         — baseline (only when BEFORE_BASE_URL set)
+ *   <surface-slug>/meta.json          — capture provenance
+ *
+ * The spec FAILS (→ route blocks) if a routed UI surface does not render its
+ * required structure — the point: an over-claimed "the UI works" cannot pass the
+ * gate without a real, passing capture bound to the SHA.
+ *
+ * ── CONSUMER REFERENCE FILE — copy into your repo and OWN it. The one block you
+ *    MUST edit is `SURFACES[]` below (your routes + their required headings +
+ *    the source globs each one covers). `df skills install verify` does NOT
+ *    overwrite this file; it is yours to maintain.
+ */
+import { test, expect, type Page } from "@playwright/test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { partitionChangedPaths, type UiSurface } from "./coverage";
+
+const SHA = process.env.DF_UI_ROUTE_SHA ?? "unknown";
+const OUT_DIR =
+  process.env.DF_UI_ROUTE_OUT ?? `agent-reviews/quality-gates/ui/${SHA}`;
+// Optional baseline origin for the "before" screenshot (e.g. the deployed
+// tip-of-main app). When unset, only the "after" capture is taken — the ARIA
+// snapshot + after screenshot are the required floor regardless.
+const BEFORE_BASE_URL = process.env.DF_UI_ROUTE_BEFORE_BASE_URL?.replace(
+  /\/$/,
+  "",
+);
+
+/**
+ * ▼▼▼ EDIT ME ▼▼▼ — the UI surfaces this producer asserts.
+ *
+ * Each entry pairs a route `path` with a stable, STRUCTURAL expectation
+ * (`requiredHeading` — an accessible-name regex for a landmark heading) so the
+ * capture also VERIFIES the surface (not just photographs it), AND a `covers`
+ * glob list declaring which changed source paths it is the evidence for (the
+ * fail-closed coverage map). Prefer role-based, copy-stable assertions.
+ *
+ * v1 ships ONE public surface (the home page) so the route works zero-auth out
+ * of the box. Replace it with your app's surfaces; add protected routes (they
+ * render under the storage-state session from the config) as your auth harness
+ * hardens.
+ */
+const SURFACES: readonly UiSurface[] = [
+  {
+    path: "/",
+    slug: "home",
+    // EDIT: a heading name (role=heading, accessible name) YOUR home page must
+    // expose. Keep it a REAL assertion — a vacuous `/.+/` ("some heading
+    // exists") neither verifies the surface nor reliably renders.
+    requiredHeading: /Welcome/i,
+    // EDIT: the source globs THIS surface (the home page) ACTUALLY renders.
+    // Keep them SCOPED. A broad glob like `web/app/**` or `web/**/*.tsx` would
+    // claim the home surface is the evidence for your WHOLE app, so a change to
+    // any OTHER page (e.g. web/app/settings/page.tsx) would be wrongly "covered"
+    // by `/` and the route would PASS without ever rendering it — defeating the
+    // fail-closed coverage below. Add one SURFACES[] entry per real surface; let
+    // anything you have not scoped fall into `uncovered` and fail closed.
+    covers: ["web/app/page.tsx"],
+  },
+];
+
+/**
+ * Changed UI paths that are NOT a renderable surface and so do not require a
+ * capture — the route's own producer harness/coverage lib, test scaffolding,
+ * type decls, styles, config. Excluding these keeps the fail-closed check
+ * honest: it fires for genuinely-uncovered *product* UI, not for the harness
+ * that implements the route. Anything NOT excluded and NOT covered by a surface
+ * blocks (fail closed) until a surface is added for it.
+ */
+const NON_SURFACE_GLOBS: readonly string[] = [
+  "web/tests/**",
+  "web/playwright.ui-route.config.ts",
+  "web/playwright.config.ts",
+  "web/**/coverage.ts",
+  "web/**/ui-route.producer.spec.ts",
+  "web/**/*.test.ts",
+  "web/**/*.test.tsx",
+  "web/**/*.spec.ts",
+  "web/**/*.d.ts",
+  "web/**/*.css",
+  "web/**/*.json",
+  "web/**/*.md",
+];
+
+const CHANGED_UI_PATHS = (process.env.DF_UI_ROUTE_CHANGED_PATHS ?? "")
+  .split(/\r?\n/)
+  .map((p) => p.trim())
+  .filter(Boolean);
+
+const {
+  armed: ARMED_SURFACES,
+  uncovered: UNCOVERED_PATHS,
+  smokeAllSurfaces: SMOKE_ALL_SURFACES,
+} = partitionChangedPaths(CHANGED_UI_PATHS, SURFACES, NON_SURFACE_GLOBS);
+
+function routeOutDir(slug: string): string {
+  return join(OUT_DIR, slug);
+}
+
+/**
+ * Optional independent VLM check (DEFERRED in v1).
+ *
+ * Additive-only: it may push a soft finding but can NEVER turn a failed floor
+ * into a pass, nor is it required for the route to pass. Wired off by default;
+ * enable with DF_UI_ROUTE_VLM=1 once you wire a provider + cost ceiling.
+ * Intentionally surfaces its intent loudly rather than faking a check (which
+ * would be the exact reward-hack this feature prevents).
+ */
+async function runOptionalVlmCheck(
+  _afterScreenshotPath: string,
+  _surface: UiSurface,
+): Promise<void> {
+  if (process.env.DF_UI_ROUTE_VLM !== "1") return;
+  test.info().annotations.push({
+    type: "vlm-check",
+    description:
+      "DF_UI_ROUTE_VLM=1 set but no VLM provider wired in this producer " +
+      "(v1 deferred). The ARIA + after floor is the gate; the VLM leg is " +
+      "additive corroboration only. No check performed.",
+  });
+}
+
+async function captureBefore(
+  page: Page,
+  surface: UiSurface,
+  dir: string,
+): Promise<void> {
+  if (!BEFORE_BASE_URL) return;
+  const beforeUrl = `${BEFORE_BASE_URL}${surface.path}`;
+  try {
+    await page.goto(beforeUrl, { waitUntil: "networkidle", timeout: 30_000 });
+    await page.screenshot({ path: join(dir, "before.png"), fullPage: true });
+  } catch (err) {
+    // The baseline is best-effort; a missing/unreachable baseline must not fail
+    // the route (the ARIA + after capture is the floor). Record why.
+    test.info().annotations.push({
+      type: "before-capture-skipped",
+      description: `baseline ${beforeUrl} unreachable: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    });
+  }
+}
+
+// FAIL-CLOSED coverage gate: if the change touched a UI path that maps to NO
+// capture surface, the route MUST block — it cannot be satisfied by rendering
+// only an unaffected surface. This is the difference between an evidence gate
+// and a false-positive generator. The fix is to ADD a surface (path +
+// requiredHeading + covers glob) for the changed area, not to widen
+// NON_SURFACE_GLOBS to hide it.
+test("ui-route-coverage — every changed UI path maps to a capture surface", async () => {
+  if (UNCOVERED_PATHS.length > 0) {
+    throw new Error(
+      "Evidence-Gated Validation playwright route: the following changed UI " +
+        "path(s) have NO mapped capture surface, so this route cannot produce " +
+        "real evidence for them and FAILS CLOSED:\n" +
+        UNCOVERED_PATHS.map((p) => `  - ${p}`).join("\n") +
+        "\n\nAdd a surface for the affected area to SURFACES[] in " +
+        "ui-route.producer.spec.ts. Do NOT widen NON_SURFACE_GLOBS to suppress " +
+        "a real UI change — that re-opens the false-positive hole this gate closes.",
+    );
+  }
+  expect(UNCOVERED_PATHS).toEqual([]);
+  // Harness-only change → smoke-capture ALL surfaces (the route still produces
+  // real evidence; it is never passable with zero captures). Surfaced so the
+  // evidence log shows why every surface was captured.
+  if (SMOKE_ALL_SURFACES) {
+    test.info().annotations.push({
+      type: "ui-route-smoke",
+      description:
+        "Harness/non-UI-only change: capturing ALL surfaces as a regression " +
+        "smoke (no product-UI surface was directly armed). The route still " +
+        "produces ARIA + after evidence — it cannot pass with zero captures.",
+    });
+  }
+});
+
+for (const surface of ARMED_SURFACES) {
+  test(`UI route evidence — ${surface.slug} (${surface.path})`, async ({
+    page,
+  }) => {
+    const dir = routeOutDir(surface.slug);
+    mkdirSync(dir, { recursive: true });
+
+    // --- (optional) BEFORE: baseline screenshot from the configured origin ---
+    await captureBefore(page, surface, dir);
+
+    // --- AFTER: the SHA under review (the locally-served / configured app) ---
+    await page.goto(surface.path, { waitUntil: "networkidle", timeout: 30_000 });
+
+    // Floor assertion — the surface renders its required structure. A REAL gate:
+    // an over-claimed render that doesn't expose the heading FAILS here, blocking
+    // the route. (Role-based → robust to copy churn.)
+    await expect(
+      page.getByRole("heading", { name: surface.requiredHeading }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    // Floor evidence #1 — ARIA snapshot (the accessibility tree). Structural,
+    // diff-able, hard to stage. Assert it is non-trivial, then persist it.
+    const ariaSnapshot = await page.locator("body").ariaSnapshot();
+    expect(ariaSnapshot.trim().length).toBeGreaterThan(0);
+    writeFileSync(join(dir, "aria.snapshot.txt"), `${ariaSnapshot}\n`, "utf8");
+
+    // Floor evidence #2 — the "after" screenshot bound to the gated SHA.
+    const afterPath = join(dir, "after.png");
+    await page.screenshot({ path: afterPath, fullPage: true });
+
+    // Per-surface metadata (the human-reviewable provenance of this capture).
+    writeFileSync(
+      join(dir, "meta.json"),
+      `${JSON.stringify(
+        {
+          surface: surface.slug,
+          path: surface.path,
+          sha: SHA,
+          capturedAt: new Date().toISOString(),
+          baseURL: test.info().project.use.baseURL ?? null,
+          beforeBaseURL: BEFORE_BASE_URL ?? null,
+          ariaSnapshotBytes: Buffer.byteLength(ariaSnapshot, "utf8"),
+          evidenceKind: "playwright",
+          floor: ["aria-snapshot", "after-screenshot"],
+          beforeScreenshot: BEFORE_BASE_URL ? "before.png" : null,
+          vlm: "deferred-v1",
+        },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+
+    // --- optional, additive-only VLM corroboration (deferred in v1) ---
+    await runOptionalVlmCheck(afterPath, surface);
+  });
+}

package/skills/verify/skill.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "../skill-schema.json",
+  "name": "verify",
+  "version": "1.0.0",
+  "summary": "Produce evidence-gated validation-route evidence for a change before pushing — drive `df verify` over the armed verification routes (terraform/helm/docker/targeted-test/UI), writing per-SHA, diffHash-bound QualityGateEvidence the local pre-push gate asserts.",
+  "originatingRepo": "momentiq-ai/dark-factory-platform",
+  "files": [
+    { "template": "SKILL.md.tmpl", "target": "SKILL.md" }
+  ],
+  "variables": {
+    "REPO_NAME": {
+      "description": "Display name of the consumer repo (e.g. 'Dark Factory Platform').",
+      "source": "darkfactory.yaml: repo.displayName",
+      "default": "this repo"
+    },
+    "ARTIFACT_DIR": {
+      "description": "Display path to the per-SHA quality-gate artifact dir (where `<sha>.json` evidence lands), used in the skill's example commands. The real value is resolved at runtime from .agent-review/config.json:git.artifactDir under the git common dir; this is the default for the docs.",
+      "source": "fixed default (the canonical .agent-review/config.json: git.artifactDir resolution)",
+      "default": ".git/agent-reviews"
+    }
+  }
+}