@bugmole/cli 0.4.0

package/scripts/ensure-maestro.cjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Ensures the `maestro` CLI is available, since Bugmole's driver shells out to
+// it for `bugmole run`. Runs as a postinstall step so installing bugmole installs
+// maestro too. Never fails the parent `npm install` — this is best-effort.
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const os = require("node:os");
+const fs = require("node:fs");
+
+function log(message) {
+  console.log(`[bugmole postinstall] ${message}`);
+}
+
+function isMaestroOnPath() {
+  const result = spawnSync("maestro", ["--version"], { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+function maestroHomeBin() {
+  return path.join(os.homedir(), ".maestro", "bin", "maestro");
+}
+
+function isMaestroInstalledButNotOnPath() {
+  return fs.existsSync(maestroHomeBin());
+}
+
+function main() {
+  if (process.env.BUGMOLE_SKIP_MAESTRO_INSTALL === "true") {
+    log("Skipping maestro install (BUGMOLE_SKIP_MAESTRO_INSTALL=true).");
+    return;
+  }
+
+  if (isMaestroOnPath()) {
+    log("maestro CLI already installed and on PATH.");
+    return;
+  }
+
+  if (isMaestroInstalledButNotOnPath()) {
+    log(
+      `maestro is installed at ${maestroHomeBin()} but not on PATH. Add ` +
+        `"${path.join(os.homedir(), ".maestro", "bin")}" to your PATH.`,
+    );
+    return;
+  }
+
+  if (process.platform === "win32") {
+    log(
+      "maestro CLI not found and there is no supported auto-install on Windows. " +
+        "Install it manually: https://maestro.mobile.dev",
+    );
+    return;
+  }
+
+  log("maestro CLI not found — installing (curl -Ls https://get.maestro.mobile.dev | bash)...");
+  const install = spawnSync("bash", ["-c", 'curl -Ls "https://get.maestro.mobile.dev" | bash'], {
+    stdio: "inherit",
+    timeout: 5 * 60 * 1000,
+  });
+
+  if (install.error || install.status !== 0) {
+    log(
+      "Automatic maestro install failed. `bugmole run` will report a blocked/driver_unavailable " +
+        'result until it is installed manually: curl -Ls "https://get.maestro.mobile.dev" | bash',
+    );
+    return;
+  }
+
+  log(
+    `maestro installed to ${maestroHomeBin()}. Ensure ` +
+      `"${path.join(os.homedir(), ".maestro", "bin")}" is on your PATH (the installer usually ` +
+      "adds this to your shell profile — restart your shell if `maestro --version` still fails).",
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  log(`Skipping maestro auto-install after unexpected error: ${error.message}`);
+}

package/scripts/ios-tunnel-keeper.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Keeps a usable iOS RemoteXPC tunnel up.
+#
+# Restarting only when the process exits is not enough: after the phone
+# reboots or the cable is re-seated, the tunnel process happily stays alive
+# holding a tunnel that no longer routes, and every developer command fails
+# with "No route to host". So health is judged by whether the RSD endpoint
+# actually answers, not by whether the process is running — a stale tunnel is
+# killed and respawned like a dead one.
+#
+# `remote tunneld` would do this properly but needs root; the native macOS
+# tunnel does not, so this supervises that instead.
+# Stop with: pkill -f ios-tunnel-keeper
+LOG=/tmp/ios-tunnel.log
+STATE=/tmp/ios-tunnel-rsd
+
+spawn() {
+  pkill -f "remote start-tunnel" 2>/dev/null
+  sleep 2
+  : > "$STATE"
+  caffeinate -s pymobiledevice3 remote start-tunnel >> "$LOG" 2>&1 &
+  # Wait for it to announce an address, rather than assuming a fixed delay.
+  for _ in $(seq 1 20); do
+    sleep 2
+    A=$(grep -oE "RSD Address: \S+" "$LOG" | tail -1 | awk '{print $3}')
+    P=$(grep -oE "RSD Port: [0-9]+" "$LOG" | tail -1 | awk '{print $3}')
+    if [ -n "$A" ] && [ -n "$P" ] && nc -z -G 3 -w 3 "$A" "$P" 2>/dev/null; then
+      printf '%s %s\n' "$A" "$P" > "$STATE"
+      echo "$(date -u +%H:%M:%S) tunnel up: $A $P" >> "$LOG"
+      return 0
+    fi
+  done
+  echo "$(date -u +%H:%M:%S) tunnel did not come up" >> "$LOG"
+  return 1
+}
+
+spawn
+while true; do
+  sleep 20
+  read -r A P < "$STATE" 2>/dev/null
+  if [ -z "$A" ] || [ -z "$P" ] || ! nc -z -G 3 -w 3 "$A" "$P" 2>/dev/null; then
+    echo "$(date -u +%H:%M:%S) tunnel stale ($A $P) — respawning" >> "$LOG"
+    spawn
+  fi
+done

package/scripts/ios-wda-keeper.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# Keeps the WebDriverAgent runner alive on an attached iPhone.
+#
+# WDA is an xcodebuild test session, not a daemon: it ends when the process
+# ends, and iOS input dies with it. Left unsupervised it simply stopped, while
+# the dashboard went on advertising an Interact button that could not work.
+#
+# It also keeps the usbmux forward to WDA's port alive, because that is how
+# the dashboard now sends input. Going through `pymobiledevice3 developer wda`
+# meant paying a Python start-up per press — 3.8s for Home, and twice that for
+# a tap, which read as "iPhone can't go home". Over this forward the same press
+# is 0.06s. The forward is over the cable rather than the phone's Wi-Fi
+# address, so it survives the phone changing network.
+#
+# Needs a built runner (see the WDA build in the repo history) and the device
+# unlocked. Stop with: pkill -f ios-wda-keeper
+UDID="${1:?usage: ios-wda-keeper.sh <udid> [wda-project-dir] [derived-data]}"
+# Not /tmp: macOS clears it, and when it did the checkout and the build tree
+# both vanished, so the keeper sat in a five-second restart loop against a
+# project that no longer existed while iOS input and recording stayed down.
+# Kept inside the repo (.local is gitignored) so it survives a reboot.
+PROJECT="${2:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/.local/WebDriverAgent}"
+DERIVED="${3:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/.local/wda-build}"
+PORT="${4:-8100}"
+# WebDriverAgent's MJPEG server, which is how an iOS run is recorded.
+MJPEG_PORT="${5:-9100}"
+LOG=/tmp/wda-run.log
+
+# Supervise the forward alongside the runner: it dies with an unplug, and
+# without it every gesture fails while WDA itself is perfectly healthy.
+forward_keeper() {
+  while true; do
+    if ! curl -sf -o /dev/null --max-time 2 "http://127.0.0.1:$PORT/status"; then
+      pkill -f "usbmux forward $PORT $PORT" 2>/dev/null
+      pymobiledevice3 usbmux forward "$PORT" "$PORT" --serial "$UDID" >> /tmp/wda-fwd.log 2>&1 &
+    fi
+    # Recording reads the MJPEG server, which is a separate port and dies
+    # independently of the one input goes through.
+    #
+    # Checked with a TCP connect, not a fetch: an MJPEG response never
+    # completes, so `curl --max-time` always exits 28 and the check can never
+    # pass. That killed and respawned this forward every five seconds — 253
+    # times before it was noticed — and would cut any recording in progress.
+    if ! nc -z 127.0.0.1 "$MJPEG_PORT" >/dev/null 2>&1; then
+      pkill -f "usbmux forward $MJPEG_PORT $MJPEG_PORT" 2>/dev/null
+      pymobiledevice3 usbmux forward "$MJPEG_PORT" "$MJPEG_PORT" --serial "$UDID" >> /tmp/wda-fwd.log 2>&1 &
+    fi
+    sleep 5
+  done
+}
+forward_keeper &
+FORWARD_KEEPER=$!
+# Take the forward supervisor down with this script, rather than leaving an
+# orphan respawning a tunnel nothing is using.
+trap 'kill "$FORWARD_KEEPER" 2>/dev/null; pkill -f "usbmux forward $PORT $PORT" 2>/dev/null; pkill -f "usbmux forward $MJPEG_PORT $MJPEG_PORT" 2>/dev/null' EXIT
+
+while true; do
+  echo "$(date -u +%H:%M:%S) starting WDA runner" >> "$LOG"
+  xcodebuild test-without-building \
+    -project "$PROJECT/WebDriverAgent.xcodeproj" \
+    -scheme WebDriverAgentRunner \
+    -destination "id=$UDID" \
+    -derivedDataPath "$DERIVED" >> "$LOG" 2>&1
+  echo "$(date -u +%H:%M:%S) WDA runner exited; restarting in 5s" >> "$LOG"
+  sleep 5
+done

package/scripts/sync-plan-catalog.d.mts

@@ -0,0 +1,3 @@
+export const catalogSource: string;
+export const catalogCopy: string;
+export const COPY_HEADER: string;

package/scripts/sync-plan-catalog.mjs

@@ -0,0 +1,16 @@
+// Copies the plan catalog into the dashboard, which deliberately builds
+// without importing files from outside apps/qa. Run after editing
+// src/billing/plan-catalog.ts; the root test suite fails if the copy drifts.
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+export const catalogSource = path.join(root, "src/billing/plan-catalog.ts");
+export const catalogCopy = path.join(root, "apps/qa/src/lib/plan-catalog.ts");
+export const COPY_HEADER = "// GENERATED by `npm run sync:catalog` from src/billing/plan-catalog.ts — edit that file instead.\n";
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const source = await readFile(catalogSource, "utf8");
+  await writeFile(catalogCopy, COPY_HEADER + source);
+  console.log(`Wrote ${path.relative(root, catalogCopy)}`);
+}

package/scripts/ui-parity-diff.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Compare normalized reference and app screenshots with Pillow."""
+
+import argparse
+import json
+from pathlib import Path
+
+from PIL import Image, ImageChops, ImageEnhance
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--reference", required=True, type=Path)
+    parser.add_argument("--actual", required=True, type=Path)
+    parser.add_argument("--output-dir", required=True, type=Path)
+    parser.add_argument("--width", type=int, default=390)
+    parser.add_argument("--height", type=int, default=844)
+    parser.add_argument("--threshold", type=int, default=16)
+    args = parser.parse_args()
+
+    if args.width <= 0 or args.height <= 0:
+        raise SystemExit("width and height must be positive")
+    if args.threshold < 0 or args.threshold > 255:
+        raise SystemExit("threshold must be between 0 and 255")
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    size = (args.width, args.height)
+    reference = Image.open(args.reference).convert("RGB").resize(size)
+    actual = Image.open(args.actual).convert("RGB").resize(size)
+    reference_path = args.output_dir / "reference-normalized.png"
+    actual_path = args.output_dir / "actual-normalized.png"
+    reference.save(reference_path)
+    actual.save(actual_path)
+
+    diff = ImageChops.difference(reference, actual)
+    changed_pixels = sum(
+        1 for pixel in diff.getdata() if max(pixel) > args.threshold
+    )
+    total_pixels = args.width * args.height
+    changed_fraction = changed_pixels / total_pixels
+    heatmap_path = args.output_dir / "heatmap.png"
+    ImageEnhance.Brightness(diff).enhance(3).save(heatmap_path)
+
+    result = {
+        "schemaVersion": 1,
+        "width": args.width,
+        "height": args.height,
+        "threshold": args.threshold,
+        "changedPixels": changed_pixels,
+        "totalPixels": total_pixels,
+        "changedFraction": changed_fraction,
+        "differencePercent": changed_fraction * 100,
+        "scoreMeaning": "0% means identical pixels; higher percentages mean more difference",
+        "referenceNormalized": str(reference_path),
+        "actualNormalized": str(actual_path),
+        "heatmap": str(heatmap_path),
+    }
+    (args.output_dir / "diff.json").write_text(
+        json.dumps(result, indent=2) + "\n", encoding="utf-8"
+    )
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/ui-parity-requirements.txt

@@ -0,0 +1 @@
+Pillow>=10.0

package/scripts/verify-manage-to-plans.mts

@@ -0,0 +1,194 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Runs the manage → plans flow against a live dashboard and records what it
+ * observed as test case verdicts.
+ *
+ * This replaces an earlier script that performed the same checks but wrote
+ * `{caseId, status, detail}` into a bespoke results.json that nothing read.
+ * Verdicts only count when they go through the test-case-results contract:
+ * that is what the dashboard reads to move a case off "planned", and what the
+ * pipeline's run stage requires before it calls a flow covered.
+ *
+ * Every result carries a detail describing what was actually seen, because
+ * bugmole_write_test_case_results rejects a verdict without one — a pass
+ * nobody can review is not evidence.
+ *
+ *   npx tsx scripts/verify-manage-to-plans.mts [--base http://localhost:3020]
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+import { chromium, type Page } from "playwright";
+import { callToolInternal } from "../src/mcp/server.js";
+
+const CASE_SET_ID = "flow-manage-to-plans-64c3c61b";
+const PROJECT = process.env.BUGMOLE_PROJECT_ID ?? "bugmole";
+const BASE = argValue("--base") ?? process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:3020";
+const ARTIFACTS = process.env.BUGMOLE_ARTIFACTS_DIR ?? "./qa/bugmole-runs";
+const SHOTS = path.join(ARTIFACTS, "projects", PROJECT, "verify", CASE_SET_ID);
+
+type Status = "passed" | "failed" | "blocked" | "needs_setup";
+type Result = { caseId: string; status: Status; detail: string; evidence?: string };
+
+function argValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+const results: Result[] = [];
+function record(caseId: string, status: Status, detail: string, evidence?: string) {
+  results.push({ caseId, status, detail, evidence });
+  const mark = status === "passed" ? "✓" : status === "failed" ? "✗" : "○";
+  console.log(`${mark} ${caseId.padEnd(24)} ${detail}`);
+}
+
+async function visible(page: Page, selector: string): Promise<boolean> {
+  return page.locator(selector).first().isVisible().catch(() => false);
+}
+
+async function shot(page: Page, name: string): Promise<string> {
+  const file = path.join(SHOTS, `${name}.png`);
+  await page.screenshot({ path: file }).catch(() => undefined);
+  return file;
+}
+
+async function main() {
+  await fs.mkdir(SHOTS, { recursive: true });
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+  page.setDefaultTimeout(15000);
+
+  try {
+    // TC-MANAGE-ENTRANCE — the manage hub renders its four resource cards.
+    await page.goto(`${BASE}/manage?project=${PROJECT}`);
+    const hubParts: Array<[string, string]> = [
+      [".auth-title", "page title"],
+      ["a.management-hub-card[href='/manage/workspaces']", "workspaces card"],
+      ["a.management-hub-card[href='/manage/projects']", "projects card"],
+      ["a.management-hub-card[href='/manage/apps']", "apps card"],
+      ["a.management-hub-card[href='/manage/environments']", "environments card"],
+      ["a.auth-back[href='/']", "back link"],
+    ];
+    const missing: string[] = [];
+    for (const [selector, label] of hubParts) {
+      if (!(await visible(page, selector))) missing.push(label);
+    }
+    record(
+      "TC-MANAGE-ENTRANCE",
+      missing.length === 0 ? "passed" : "failed",
+      missing.length === 0
+        ? "/manage rendered the title, all four resource cards and the back link"
+        : `/manage was missing: ${missing.join(", ")}`,
+      await shot(page, "01-manage"),
+    );
+
+    // TC-MANAGE-NAV-PLANS — the sidebar link reaches /plans carrying project context.
+    await page.getByRole("link", { name: "Test plans", exact: true }).click().catch(() => undefined);
+    await page.waitForLoadState("networkidle").catch(() => undefined);
+    const onPlans = /\/plans/.test(page.url());
+    const keptProject = page.url().includes(`project=${PROJECT}`);
+    record(
+      "TC-MANAGE-NAV-PLANS",
+      onPlans && keptProject ? "passed" : "failed",
+      onPlans && keptProject
+        ? `sidebar navigation reached ${page.url()} with project context intact`
+        : onPlans
+          ? `reached /plans but the sidebar dropped ?project=${PROJECT} (url was ${page.url()})`
+          : `sidebar navigation did not reach /plans (url was ${page.url()})`,
+      await shot(page, "02-plans"),
+    );
+
+    // Continue from a known-good URL so one navigation defect does not cascade
+    // into failures for cases that are really about the plans workspace.
+    if (!onPlans || !keptProject) {
+      await page.goto(`${BASE}/plans?project=${PROJECT}`);
+      await page.waitForLoadState("networkidle").catch(() => undefined);
+    }
+
+    // TC-PLANS-GOAL — the plans workspace renders, both by navigation and directly.
+    await page.locator("section#plans .plan-list").waitFor({ state: "visible", timeout: 10000 }).catch(() => undefined);
+    const goalParts = [
+      await visible(page, "section#plans"),
+      await visible(page, "section#plans .plan-list"),
+    ];
+    record(
+      "TC-PLANS-GOAL",
+      goalParts.every(Boolean) ? "passed" : "failed",
+      goalParts.every(Boolean)
+        ? "the plans section and its plan list rendered on a direct load of /plans"
+        : `plans workspace incomplete: section=${goalParts[0]}, planList=${goalParts[1]}`,
+      await shot(page, "03-plans-workspace"),
+    );
+
+    // TC-PLANS-SELECT-PLAN — selecting a plan row enables the start button.
+    const rows = page.locator("button.plan-row");
+    const rowCount = await rows.count();
+    if (rowCount === 0) {
+      // Nothing to select, so nothing was proven either way. "blocked" says
+      // the check could not run, which is the honest verdict — not a failure
+      // of the behaviour under test.
+      record("TC-PLANS-SELECT-PLAN", "blocked", "no plan rows rendered, so selection could not be exercised");
+      record("TC-PLANS-START-BLOCKED", "blocked", "no plan could be selected, so starting one could not be exercised");
+    } else {
+      await rows.first().click();
+      const pressed = await rows.first().getAttribute("aria-pressed");
+      const startEnabled = await visible(page, "button.plan-start-button:not([disabled])");
+      record(
+        "TC-PLANS-SELECT-PLAN",
+        pressed === "true" && startEnabled ? "passed" : "failed",
+        pressed === "true" && startEnabled
+          ? "clicking a plan row set aria-pressed=true and enabled the start button"
+          : `after clicking a plan row: aria-pressed=${pressed}, start button enabled=${startEnabled}`,
+        await shot(page, "04-plan-selected"),
+      );
+
+      // TC-PLANS-START-BLOCKED — starting posts a run, even with no worker attached.
+      const runPost = page.waitForResponse(
+        (response) => response.url().includes(`/api/projects/${PROJECT}/runs`) && response.request().method() === "POST",
+        { timeout: 10000 },
+      ).catch(() => null);
+      await page.locator("button.plan-start-button").click();
+      const response = await runPost;
+      const ok = response !== null && [200, 201].includes(response.status());
+      record(
+        "TC-PLANS-START-BLOCKED",
+        ok ? "passed" : "failed",
+        ok
+          ? `starting the plan posted to /api/projects/${PROJECT}/runs and returned ${response!.status()}`
+          : response === null
+            ? "starting the plan sent no POST to the runs endpoint within 10s"
+            : `the runs endpoint returned ${response.status()}`,
+        await shot(page, "05-start-plan"),
+      );
+    }
+
+    // TC-PLANS-AUTH-REDIRECT — unauthenticated /plans should redirect to login.
+    // The local dev bypass authenticates every request, so this cannot be
+    // exercised here at all; saying so is more useful than a pass or a fail.
+    record(
+      "TC-PLANS-AUTH-REDIRECT",
+      "blocked",
+      "BUGMOLE_LOCAL_DEV_BYPASS_AUTH authenticates every local request, so the unauthenticated redirect cannot be observed against this environment",
+    );
+  } finally {
+    await browser.close();
+  }
+
+  const cfg = {
+    project: { id: PROJECT },
+    runtime: { spec_dir: process.env.BUGMOLE_SPEC_DIR ?? "./spec", artifacts_dir: ARTIFACTS },
+    storage: { provider: "local", localDirectory: ARTIFACTS },
+  } as any;
+
+  const written = await callToolInternal("bugmole_write_test_case_results", {
+    resultSet: { schemaVersion: 1, caseSetId: CASE_SET_ID, results },
+  }, cfg);
+
+  console.log(`\nrecorded ${written.recorded}/${written.of} cases → ${written.objectKey}`);
+  console.log(JSON.stringify(written.counts));
+  process.exit(results.some((result) => result.status === "failed") ? 1 : 0);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/spec/app-ui-audit.schema.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://app.bugmole.com/schemas/app-ui-audit.schema.json",
+  "title": "Bugmole Application UI Audit",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "auditId",
+    "requestedFlow",
+    "journeyId",
+    "journeyRevision",
+    "flowStatus",
+    "exploredNodeIds",
+    "exploredEdgeIds",
+    "summary",
+    "screens",
+    "highestPriorityMissingImplementations",
+    "blockedVerification"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "auditId": { "type": "string", "minLength": 1 },
+    "workspaceId": { "type": "string" },
+    "projectId": { "type": "string" },
+    "actor": { "type": "string" },
+    "baseUrl": { "type": "string", "format": "uri" },
+    "requestedFlow": { "type": "string", "minLength": 1 },
+    "journeyId": { "type": "string", "minLength": 1 },
+    "journeyRevision": { "type": "integer", "minimum": 1 },
+    "flowStatus": { "enum": ["exhausted", "blocked"] },
+    "exploredNodeIds": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "exploredEdgeIds": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "blockerResolutionId": { "type": "string", "minLength": 1 },
+    "clarification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fingerprint", "question", "reason"],
+      "properties": {
+        "fingerprint": { "type": "string", "minLength": 1 },
+        "question": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["needed", "remembered", "resolved"] }
+      }
+    },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "implemented", "partiallyImplemented", "notImplemented"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "implemented": { "type": "integer", "minimum": 0 },
+        "partiallyImplemented": { "type": "integer", "minimum": 0 },
+        "notImplemented": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "screens": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["screenId", "controls"],
+        "properties": {
+          "screenId": { "type": "string", "minLength": 1 },
+          "route": { "type": "string" },
+          "title": { "type": "string" },
+          "controls": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/control" }
+          }
+        }
+      }
+    },
+    "highestPriorityMissingImplementations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/issue" }
+    },
+    "blockedVerification": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["description", "reason"],
+        "properties": {
+          "description": { "type": "string" },
+            "reason": { "type": "string" },
+            "fingerprint": { "type": "string", "minLength": 1 },
+            "question": { "type": "string", "minLength": 1 },
+            "status": { "enum": ["needed", "remembered", "resolved"] },
+            "resolutionId": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "description"],
+      "properties": {
+        "type": { "enum": ["runtime", "source"] },
+        "medium": { "enum": ["screenshot", "video", "log", "other"] },
+        "description": { "type": "string" },
+        "location": { "type": "string", "minLength": 1 }
+      },
+      "if": { "properties": { "type": { "const": "runtime" } } },
+      "then": {
+        "required": ["type", "description", "location"]
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["description"],
+      "properties": {
+        "description": { "type": "string" },
+        "priority": { "enum": ["high", "medium", "low"] },
+        "screenId": { "type": "string" },
+        "controlId": { "type": "string" }
+      }
+    },
+    "control": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "controlId",
+        "label",
+        "kind",
+        "status",
+        "destinationOrHandler",
+        "evidence",
+        "missingBehavior"
+      ],
+      "properties": {
+        "controlId": { "type": "string", "minLength": 1 },
+        "label": { "type": "string" },
+        "kind": {
+          "enum": [
+            "button",
+            "link",
+            "row",
+            "card",
+            "tab",
+            "form",
+            "selectable",
+            "cta",
+            "menu",
+            "external",
+            "other"
+          ]
+        },
+        "status": {
+          "enum": ["Implemented", "Partially implemented", "Not implemented"]
+        },
+        "destinationOrHandler": { "type": "string" },
+        "evidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/evidence" }
+        },
+        "missingBehavior": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "priority": { "enum": ["high", "medium", "low"] }
+      }
+    }
+  }
+}