@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/clis/maggie_design_lint.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Static design checks that catch defects before a browser run.
+
+``pressable-check`` flags a pressable or button rendered inside another
+pressable in JSX/TSX. React Native Web renders ``Pressable`` and the
+``Touchable*`` family as ``<button>``-like elements, so a chip with a nested
+remove control becomes ``<button>`` inside ``<button>``: invalid DOM, and taps
+land on the wrong control.
+
+``layer-check`` flags unlayered CSS that competes with Tailwind v4 utilities.
+Tailwind v4 emits utilities inside ``@layer utilities``; any unlayered rule
+wins over every layer regardless of specificity, so an unlayered
+``h1 { font-family }`` beats ``font-*`` and ``.ph { display: inline-block }``
+beats ``hidden`` and ``group-open:inline``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+SKIP_DIRS = {"node_modules", "dist", "build", ".git", ".expo", ".next", ".astro", ".output", "coverage", ".maggie", ".turbo", ".vercel", ".wrangler"}
+PRESSABLES = ("Pressable", "TouchableOpacity", "TouchableHighlight", "TouchableWithoutFeedback", "TouchableNativeFeedback", "button", "a")
+ALLOW_MARKER = "maggie-allow-nested-pressable"
+JSX_KEYWORDS = {"return", "yield", "await", "default", "case", "in", "of", "else", "do"}
+
+TAILWIND_V4_IMPORT = re.compile(r"""@import\s+(?:url\()?["']tailwindcss["']""")
+LAYERED_IMPORT = re.compile(r"""@import\s+(?:url\()?["']([^"']+)["']\)?\s+layer\(""")
+# At-rules whose bodies are Tailwind theme/utility definitions or descriptors, not competing rules.
+SKIPPED_AT_RULES = {"theme", "utility", "variant", "custom-variant", "keyframes", "font-face", "property", "plugin", "source", "page", "counter-style", "font-feature-values", "starting-style"}
+NESTING_AT_RULES = {"media", "supports", "container", "scope", "document"}
+COMPETING_PROPERTIES = re.compile(
+    r"^(display|visibility|font-family|font-size|font-weight|font-style|line-height|letter-spacing|text-transform|"
+    r"text-align|color|background(-color)?|margin(-[a-z]+)?|padding(-[a-z]+)?|width|height|min-width|max-width|"
+    r"min-height|max-height|gap|border(-[a-z]+)*|position|inset|top|right|bottom|left|z-index|opacity)$"
+)
+ICON_CLASS = re.compile(r"\.(ph|ph-[\w-]+|fa|fa[srb]|fa-[\w-]+|bi|bi-[\w-]+|material-icons[\w-]*|material-symbols[\w-]*|icon|icon-[\w-]+|lucide|lucide-[\w-]+|iconify)(?![\w-])")
+ICON_ATTRIBUTE = re.compile(r"""\[class[\^*|]?=\s*["']?(ph|fa|bi|icon)""")
+TYPE_SELECTOR = re.compile(r"^(\*|[a-zA-Z][a-zA-Z0-9-]*)")
+
+
+def iter_files(roots: list[Path], suffixes: tuple[str, ...]) -> list[Path]:
+    found: list[Path] = []
+    for root in roots:
+        if root.is_file():
+            if root.suffix in suffixes:
+                found.append(root)
+            continue
+        for path in sorted(root.rglob("*")):
+            if path.suffix in suffixes and path.is_file() and not any(part in SKIP_DIRS for part in path.relative_to(root).parts):
+                found.append(path)
+    return found
+
+
+def _display(path: Path, project: Path) -> str:
+    try:
+        return path.resolve().relative_to(project.resolve()).as_posix()
+    except ValueError:
+        return path.name
+
+
+# ---------------------------------------------------------------- pressables
+
+def _strip_jsx_comments(source: str) -> str:
+    """Blank comments while keeping offsets, so line numbers stay correct."""
+    def blank(match: re.Match[str]) -> str:
+        return re.sub(r"[^\n]", " ", match.group(0))
+    source = re.sub(r"/\*.*?\*/", blank, source, flags=re.S)
+    return re.sub(r"(?m)^[ \t]*//[^\n]*", blank, source)
+
+
+def _scan_tag(source: str, start: int) -> tuple[int, bool, str] | None:
+    """Return (end offset, self-closing, attribute text) for a tag at ``start``."""
+    depth = 0
+    quote = ""
+    index = start
+    while index < len(source):
+        char = source[index]
+        if quote:
+            if char == quote and source[index - 1] != "\\":
+                quote = ""
+        elif char in "\"'`":
+            quote = char
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+        elif char == ">" and depth == 0:
+            return index + 1, source[index - 1] == "/", source[start:index]
+        index += 1
+    return None
+
+
+def pressable_findings(path: Path, names: set[str], display: str) -> list[dict[str, object]]:
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    source = _strip_jsx_comments(raw)
+    raw_lines = raw.splitlines()
+    findings: list[dict[str, object]] = []
+    stack: list[tuple[str, bool, int]] = []  # (tag, is_pressable_boundary, line)
+    for match in re.finditer(r"<(/?)([A-Za-z][\w.]*)", source):
+        before = source[:match.start()].rstrip()
+        closing = match.group(1) == "/"
+        name = match.group(2)
+        # A preceding identifier character means a TypeScript generic, not JSX.
+        if not closing and before and (before[-1].isalnum() or before[-1] in "_$."):
+            word = re.search(r"[\w$]+$", before)
+            if not word or word.group(0) not in JSX_KEYWORDS:
+                continue
+        line = source.count("\n", 0, match.start()) + 1
+        if closing:
+            for position in range(len(stack) - 1, -1, -1):
+                if stack[position][0] == name:
+                    del stack[position:]
+                    break
+            continue
+        scanned = _scan_tag(source, match.end())
+        if scanned is None:
+            continue
+        _, self_closing, attributes = scanned
+        is_pressable = name in names
+        # `asChild` delegates rendering to the child (expo-router Link), so it is not a second control.
+        boundary = is_pressable and not re.search(r"\basChild\b", attributes)
+        if is_pressable:
+            outer = next((entry for entry in reversed(stack) if entry[1]), None)
+            allowed = ALLOW_MARKER in (raw_lines[line - 1] if line - 1 < len(raw_lines) else "")
+            if outer and not allowed:
+                findings.append({
+                    "file": display, "line": line, "inner": name, "outer": outer[0], "outerLine": outer[2],
+                    "message": f"<{name}> is nested inside <{outer[0]}> (line {outer[2]}); render them as sibling pressables",
+                })
+        if not self_closing:
+            stack.append((name, boundary, line))
+    return findings
+
+
+def pressable_check(project: Path, paths: list[Path], extra: list[str]) -> dict[str, object]:
+    names = set(PRESSABLES) | set(extra)
+    files = iter_files(paths or [project], (".tsx", ".jsx"))
+    findings: list[dict[str, object]] = []
+    for path in files:
+        findings.extend(pressable_findings(path, names, _display(path, project)))
+    return {"schemaVersion": "maggie-design-pressable-check.v1", "passed": not findings, "checkedFiles": len(files), "pressables": sorted(names), "findings": findings}
+
+
+# ---------------------------------------------------------------- CSS layers
+
+def _strip_css_comments(source: str) -> str:
+    return re.sub(r"/\*.*?\*/", lambda match: re.sub(r"[^\n]", " ", match.group(0)), source, flags=re.S)
+
+
+def _block_end(source: str, open_index: int) -> int:
+    depth = 0
+    quote = ""
+    for index in range(open_index, len(source)):
+        char = source[index]
+        if quote:
+            if char == quote and source[index - 1] != "\\":
+                quote = ""
+        elif char in "\"'":
+            quote = char
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return index
+    return len(source) - 1
+
+
+def _selector_kind(selector: str) -> str | None:
+    if ICON_CLASS.search(selector) or ICON_ATTRIBUTE.search(selector):
+        return "icon"
+    kind = None
+    for part in selector.split(","):
+        compounds = [item for item in re.split(r"\s*[>+~]\s*|\s+", part.strip()) if item]
+        if not compounds:
+            continue
+        last = re.sub(r"::?[\w-]+(\([^)]*\))?", "", compounds[-1])
+        match = TYPE_SELECTOR.match(last)
+        if not match:
+            continue
+        if match.group(1).lower() in {"html", "body"}:
+            kind = kind or "root"
+        else:
+            return "element"
+    return kind
+
+
+def _rule_findings(source: str, start: int, end: int, layered: bool, display: str, findings: list[dict[str, object]]) -> None:
+    index = start
+    while index < end:
+        brace = source.find("{", index, end)
+        semicolon = source.find(";", index, end)
+        if brace == -1:
+            return
+        if semicolon != -1 and semicolon < brace:
+            index = semicolon + 1  # statement at-rule such as @import or @layer a, b;
+            continue
+        prelude = source[index:brace].strip()
+        close = _block_end(source, brace)
+        if prelude.startswith("@"):
+            at_name = re.match(r"@([\w-]+)", prelude)
+            name = at_name.group(1).lower() if at_name else ""
+            if name == "layer":
+                _rule_findings(source, brace + 1, close, True, display, findings)
+            elif name in NESTING_AT_RULES:
+                _rule_findings(source, brace + 1, close, layered, display, findings)
+        elif not layered and prelude:
+            kind = _selector_kind(prelude)
+            body = source[brace + 1:close]
+            properties = sorted({item.split(":", 1)[0].strip().lower() for item in body.split(";") if ":" in item and "{" not in item.split(":", 1)[0]})
+            competing = [item for item in properties if COMPETING_PROPERTIES.match(item)]
+            line = source.count("\n", 0, index + (len(source[index:brace]) - len(source[index:brace].lstrip()))) + 1
+            if kind == "root" and competing:
+                findings.append({
+                    "file": display, "line": line, "selector": " ".join(prelude.split()), "kind": kind, "properties": competing, "severity": "warning",
+                    "message": "unlayered html/body rule overrides utilities placed on that element; prefer @layer base",
+                })
+            elif kind and competing:
+                findings.append({
+                    "file": display, "line": line, "selector": " ".join(prelude.split()), "kind": kind, "properties": competing, "severity": "error",
+                    "message": f"unlayered {kind} rule sets {', '.join(competing)} and overrides Tailwind v4 utilities; move it into @layer {'components' if kind == 'icon' else 'base'}",
+                })
+            elif not kind and "display" in competing:
+                findings.append({
+                    "file": display, "line": line, "selector": " ".join(prelude.split()), "kind": "class", "properties": ["display"], "severity": "warning",
+                    "message": "unlayered rule sets display, so utilities such as hidden cannot toggle this element; prefer @layer components",
+                })
+        index = close + 1
+
+
+def layer_check(project: Path, paths: list[Path], force_v4: bool) -> dict[str, object]:
+    files = iter_files(paths or [project], (".css", ".pcss", ".postcss"))
+    sources = {path.resolve(): _strip_css_comments(path.read_text(encoding="utf-8", errors="replace")) for path in files}
+    tailwind_v4 = force_v4 or any(TAILWIND_V4_IMPORT.search(source) for source in sources.values())
+    if not tailwind_v4:
+        return {"schemaVersion": "maggie-design-layer-check.v1", "passed": True, "status": "skipped", "reason": "no Tailwind v4 entry (@import \"tailwindcss\") found", "checkedFiles": len(files), "findings": []}
+    layered_files: set[Path] = set()
+    for path, source in sources.items():
+        for target in LAYERED_IMPORT.findall(source):
+            layered_files.add((path.parent / target).resolve())
+    findings: list[dict[str, object]] = []
+    for path, source in sources.items():
+        _rule_findings(source, 0, len(source), path in layered_files, _display(path, project), findings)
+    errors = [item for item in findings if item["severity"] == "error"]
+    return {"schemaVersion": "maggie-design-layer-check.v1", "passed": not errors, "status": "checked", "checkedFiles": len(files), "errors": len(errors), "warnings": len(findings) - len(errors), "findings": findings}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design", description="Static design checks that run before browser QA.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    pressable = sub.add_parser("pressable-check", help="flag pressables or buttons nested inside another pressable (.tsx/.jsx)")
+    pressable.add_argument("--project", type=Path, default=Path.cwd())
+    pressable.add_argument("--path", type=Path, action="append", default=[], help="file or directory to scan; defaults to the project")
+    pressable.add_argument("--pressable", action="append", default=[], help="extra component name that renders a pressable, for example Chip")
+    layers = sub.add_parser("layer-check", help="flag unlayered CSS that overrides Tailwind v4 utilities")
+    layers.add_argument("--project", type=Path, default=Path.cwd())
+    layers.add_argument("--css", type=Path, action="append", default=[], help="CSS file or directory to scan; defaults to the project")
+    layers.add_argument("--tailwind-v4", action="store_true", help="check even when no @import \"tailwindcss\" entry is found")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "pressable-check":
+            report = pressable_check(args.project, args.path, args.pressable)
+        else:
+            report = layer_check(args.project, args.css, args.tailwind_v4)
+    except OSError as error:
+        print(f"BLOCKED: maggie-design {args.command}: {error}", file=sys.stderr)
+        return 1
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_design_verify.py

@@ -0,0 +1,359 @@
+#!/usr/bin/env python3
+"""Orchestrate evidence for a Maggie design job and record completed steps.
+
+``maggie design verify JOB_ID`` runs every *automatable* step of an in-place,
+section-scoped, or author design job against a host adapter — a running
+server (``--base-url``) or a static build (``--dist``) — writes durable
+evidence under ``.maggie/design-evidence/<job>/``, and records a step as done
+only when its check passed. Steps that need an implementer or a person
+(``apply-design-contract``, ``implement-*``, ``visual-review``, ``approval``)
+are never completed here; record them with ``maggie design step`` and real
+evidence. A job therefore cannot reach ``done`` without evidence.
+
+Section jobs are two-stage: run ``--stage before`` before editing (captures the
+section snapshot) and the default ``--stage after`` once implemented.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urlsplit
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from maggie_design import REVIEW_VIEWPORTS, find_design_job_path, validate_section_evidence  # noqa: E402
+from maggie_icon_glyph_check import _ProbeServer, find_chrome  # noqa: E402
+
+SCHEMA = "maggie-design-verify.v1"
+MANUAL_STEPS = {"apply-design-contract", "implement-section", "implement-page", "visual-review", "approval"}
+INSPECT_STEPS = {"inspect-route", "inspect-shell", "inspect-section"}
+PLACEHOLDERS = re.compile(r"\{\{[^}]*\}\}|\[object Object\]|\bundefined\b|lorem ipsum", re.I)
+VOID_TAGS = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"}
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class PageFacts(HTMLParser):
+    """Collect bounded structural facts and per-section hashes from HTML."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.title = ""; self._in_title = False; self.lang = ""
+        self.h1 = 0; self.landmarks: set[str] = set(); self.ids: set[str] = set()
+        self.images_without_alt = 0; self.unnamed_controls = 0; self.unlabelled_inputs = 0
+        self.robots_noindex = False; self.text_parts: list[str] = []
+        self._labels_for: set[str] = set(); self._input_ids: list[tuple[str, bool]] = []
+        self._control_stack: list[dict] = []; self._label_depth = 0
+        self.sections: dict[str, list[str]] = {}; self._open_sections: list[tuple[str, int]] = []; self._depth = 0
+
+    def _section_id(self, tag: str, attrs: dict[str, str]) -> str | None:
+        explicit = attrs.get("data-section-id") or attrs.get("data-maggie-section")
+        if explicit:
+            return explicit
+        return attrs.get("id") if tag == "section" and attrs.get("id") else None
+
+    def _record(self, token: str) -> None:
+        for section_id, _depth in self._open_sections:
+            self.sections[section_id].append(token)
+
+    def handle_starttag(self, tag: str, attr_list: list[tuple[str, str | None]]) -> None:
+        attrs = {name: value or "" for name, value in attr_list}
+        void = tag in VOID_TAGS
+        if not void:
+            self._depth += 1
+        section_id = self._section_id(tag, attrs)
+        if section_id and not void:
+            self.sections.setdefault(section_id, [])
+            self._open_sections.append((section_id, self._depth))
+        self._record("<" + tag + "".join(f" {k}={v}" for k, v in sorted(attrs.items()) if k not in {"nonce"}) + ">")
+        if attrs.get("id"):
+            self.ids.add(attrs["id"])
+        if tag == "html":
+            self.lang = attrs.get("lang", "")
+        elif tag == "title":
+            self._in_title = True
+        elif tag == "h1":
+            self.h1 += 1
+        elif tag in {"header", "main", "footer", "nav"}:
+            self.landmarks.add(tag)
+        elif tag == "meta" and attrs.get("name", "").lower() == "robots" and "noindex" in attrs.get("content", "").lower():
+            self.robots_noindex = True
+        elif tag == "img" and "alt" not in attrs:
+            self.images_without_alt += 1
+        elif tag == "label":
+            self._label_depth += 1
+            if attrs.get("for"):
+                self._labels_for.add(attrs["for"])
+        elif tag in {"input", "select", "textarea"} and attrs.get("type", "").lower() not in {"hidden", "submit", "button", "reset", "image"}:
+            named = bool(attrs.get("aria-label") or attrs.get("aria-labelledby") or attrs.get("title") or self._label_depth)
+            self._input_ids.append((attrs.get("id", ""), named))
+        if tag in {"a", "button"} and not void:
+            named = bool(attrs.get("aria-label") or attrs.get("aria-labelledby") or attrs.get("title"))
+            self._control_stack.append({"tag": tag, "named": named, "text": ""})
+        if tag == "img" and self._control_stack and attrs.get("alt"):
+            self._control_stack[-1]["named"] = True
+
+    def handle_endtag(self, tag: str) -> None:
+        self._record("</" + tag + ">")
+        if tag == "title":
+            self._in_title = False
+        elif tag == "label" and self._label_depth:
+            self._label_depth -= 1
+        if tag in {"a", "button"} and self._control_stack and self._control_stack[-1]["tag"] == tag:
+            control = self._control_stack.pop()
+            if not control["named"] and not control["text"].strip():
+                self.unnamed_controls += 1
+        if tag not in VOID_TAGS:
+            while self._open_sections and self._open_sections[-1][1] >= self._depth:
+                self._open_sections.pop()
+            self._depth = max(0, self._depth - 1)
+
+    def handle_data(self, data: str) -> None:
+        if self._in_title:
+            self.title += data
+        text = " ".join(data.split())
+        if text:
+            self._record(text)
+            self.text_parts.append(text)
+            for control in self._control_stack:
+                control["text"] += text
+
+    def finish(self) -> dict:
+        unlabelled = sum(1 for input_id, named in self._input_ids if not named and not (input_id and input_id in self._labels_for))
+        return {
+            "title": self.title.strip()[:200], "lang": self.lang, "h1Count": self.h1, "landmarks": sorted(self.landmarks),
+            "imagesWithoutAlt": self.images_without_alt, "unnamedControls": self.unnamed_controls, "unlabelledInputs": unlabelled,
+            "robotsNoindex": self.robots_noindex,
+            "placeholders": sorted({match.group(0)[:40] for match in PLACEHOLDERS.finditer(" ".join(self.text_parts))}),
+            "sections": [{"id": section_id, "hash": hashlib.sha256("\n".join(tokens).encode("utf-8")).hexdigest(), "tokens": len(tokens)} for section_id, tokens in sorted(self.sections.items())],
+        }
+
+
+def page_facts(document: str) -> dict:
+    parser = PageFacts()
+    parser.feed(document)
+    parser.close()
+    return parser.finish()
+
+
+def job_routes(job: dict) -> list[str]:
+    if isinstance(job.get("routes"), list) and job["routes"]:
+        return [item["route"] if isinstance(item, dict) else str(item) for item in job["routes"]]
+    if job.get("route"):
+        return [str(job["route"])]
+    if job.get("brief") and Path(job["brief"]).is_file():
+        return [json.loads(Path(job["brief"]).read_text(encoding="utf-8"))["route"]]
+    raise ValueError("design job has no routes to verify")
+
+
+class Verifier:
+    def __init__(self, project: Path, job_id: str, server: _ProbeServer, chrome: str | None, stage: str, build_command: str | None, budget_ms: int) -> None:
+        self.project = project; self.job_id = job_id; self.server = server; self.chrome = chrome
+        self.stage = stage; self.build_command = build_command; self.budget_ms = budget_ms
+        self.job_path = find_design_job_path(project, job_id)
+        self.job = json.loads(self.job_path.read_text(encoding="utf-8"))
+        self.routes = job_routes(self.job)
+        self.evidence_dir = project / ".maggie" / "design-evidence" / job_id
+        self.evidence_dir.mkdir(parents=True, exist_ok=True)
+        self._pages: dict[str, tuple[int, str, str]] = {}
+
+    def page(self, route: str) -> tuple[int, str, str]:
+        if route not in self._pages:
+            status, content_type, body = self.server.fetch(route)
+            self._pages[route] = (status, content_type, body.decode("utf-8", errors="replace"))
+        return self._pages[route]
+
+    def rendered(self, route: str) -> str:
+        if not self.chrome:
+            return self.page(route)[2]
+        proc = subprocess.run([self.chrome, "--headless=new", "--no-sandbox", "--disable-gpu", f"--virtual-time-budget={self.budget_ms}", "--dump-dom", self.server.origin + route], capture_output=True, text=True, timeout=180, check=False)
+        return proc.stdout if proc.returncode == 0 and proc.stdout.strip() else self.page(route)[2]
+
+    def write(self, name: str, payload: dict) -> Path:
+        path = self.evidence_dir / f"{name}.json"
+        path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        return path
+
+    # -- step checks: return (passed, evidence payload) ----------------------
+
+    def inspect(self, step: str) -> tuple[bool, dict]:
+        results, errors = [], []
+        for route in self.routes:
+            status, content_type, document = self.page(route)
+            facts = page_facts(document) if "html" in content_type else {}
+            results.append({"route": route, "status": status, "contentType": content_type.split(";")[0], "title": facts.get("title"), "landmarks": facts.get("landmarks"), "sectionIds": [item["id"] for item in facts.get("sections", [])], "sha256": hashlib.sha256(document.encode("utf-8")).hexdigest()})
+            if not 200 <= status <= 299 or "html" not in content_type:
+                errors.append(f"{route}: HTTP {status} {content_type.split(';')[0]}")
+            if step == "inspect-shell" and not {"header", "footer"} <= set(facts.get("landmarks", [])):
+                errors.append(f"{route}: canonical shell needs header and footer landmarks")
+            if step == "inspect-section" and self.job.get("sectionId") not in {item["id"] for item in facts.get("sections", [])}:
+                errors.append(f"{route}: section {self.job.get('sectionId')!r} not found (use <section id> or data-section-id)")
+        return not errors, {"routes": results, "errors": errors}
+
+    def declare_content_source(self) -> tuple[bool, dict]:
+        routes = [item for item in self.job.get("routes", []) if isinstance(item, dict)]
+        unproven = [item["route"] for item in routes if item.get("resolution") == "unproven"]
+        return not unproven and bool(routes), {"routes": [{key: item.get(key) for key in ("route", "resolution", "contentSource")} for item in routes], "errors": [f"{route}: catch-all content source not declared; recreate the job with --content-source" for route in unproven]}
+
+    def snapshot(self, label: str) -> tuple[bool, dict]:
+        route = self.routes[0]
+        status, _content_type, _document = self.page(route)
+        facts = page_facts(self.rendered(route))
+        payload = {"schemaVersion": "maggie-section-snapshot.v1", "route": route, "status": status, "label": label, "sections": [{"id": item["id"], "hash": item["hash"]} for item in facts["sections"]]}
+        errors = [] if 200 <= status <= 299 and payload["sections"] else [f"{route}: no sections captured (HTTP {status})"]
+        payload["errors"] = errors
+        return not errors, payload
+
+    def unchanged_rest(self) -> tuple[bool, dict]:
+        before = self.evidence_dir / "capture-before.json"
+        after = self.evidence_dir / "capture-after.json"
+        if not before.is_file() or not after.is_file():
+            return False, {"errors": ["capture-before and capture-after evidence are both required; run --stage before first"]}
+        result = validate_section_evidence(before, after, str(self.job.get("sectionId")))
+        return bool(result["passed"]), result
+
+    def screenshots(self) -> tuple[bool, dict]:
+        if not self.chrome:
+            return False, {"errors": ["google-chrome or chromium is required for screenshots"]}
+        shots, errors = [], []
+        for route in self.routes:
+            slug = re.sub(r"[^a-z0-9]+", "-", route.lower()).strip("-") or "home"
+            for viewport, (width, height) in REVIEW_VIEWPORTS.items():
+                target = self.evidence_dir / "screenshots" / f"{slug}-{viewport}.png"
+                target.parent.mkdir(parents=True, exist_ok=True)
+                proc = subprocess.run([self.chrome, "--headless=new", "--no-sandbox", "--disable-gpu", "--hide-scrollbars", f"--window-size={width},{height}", f"--virtual-time-budget={self.budget_ms}", f"--screenshot={target}", self.server.origin + route], capture_output=True, text=True, timeout=180, check=False)
+                if proc.returncode != 0 or not target.is_file() or target.stat().st_size == 0:
+                    errors.append(f"{route} @ {viewport}: screenshot failed")
+                    continue
+                shots.append({"route": route, "viewport": viewport, "size": [width, height], "path": str(target), "sha256": hashlib.sha256(target.read_bytes()).hexdigest()})
+        return not errors and bool(shots), {"screenshots": shots, "errors": errors}
+
+    def accessibility(self) -> tuple[bool, dict]:
+        results, errors = [], []
+        for route in self.routes:
+            facts = page_facts(self.rendered(route))
+            item = {key: facts[key] for key in ("lang", "h1Count", "imagesWithoutAlt", "unnamedControls", "unlabelledInputs", "landmarks")}
+            item["route"] = route
+            results.append(item)
+            if not facts["lang"]: errors.append(f"{route}: <html> has no lang")
+            if facts["h1Count"] != 1: errors.append(f"{route}: expected exactly one h1, found {facts['h1Count']}")
+            if facts["imagesWithoutAlt"]: errors.append(f"{route}: {facts['imagesWithoutAlt']} image(s) without alt")
+            if facts["unnamedControls"]: errors.append(f"{route}: {facts['unnamedControls']} link/button(s) without an accessible name")
+            if facts["unlabelledInputs"]: errors.append(f"{route}: {facts['unlabelledInputs']} form field(s) without a label")
+            if "main" not in facts["landmarks"]: errors.append(f"{route}: no <main> landmark")
+        return not errors, {"routes": results, "errors": errors, "scope": "static rendered-DOM checks; not a substitute for assistive-technology testing"}
+
+    def route_validation(self) -> tuple[bool, dict]:
+        results, errors = [], []
+        for route in self.routes:
+            status, content_type, _document = self.page(route)
+            facts = page_facts(self.rendered(route)) if "html" in content_type else {"title": "", "h1Count": 0, "placeholders": [], "robotsNoindex": False}
+            results.append({"route": route, "status": status, "title": facts["title"], "h1Count": facts["h1Count"], "placeholders": facts["placeholders"], "robotsNoindex": facts["robotsNoindex"]})
+            if not 200 <= status <= 299: errors.append(f"{route}: HTTP {status}")
+            if not facts["title"]: errors.append(f"{route}: empty <title>")
+            if facts["h1Count"] < 1: errors.append(f"{route}: no h1")
+            if facts["placeholders"]: errors.append(f"{route}: unresolved placeholder text {facts['placeholders']}")
+            if facts["robotsNoindex"]: errors.append(f"{route}: robots noindex present")
+        return not errors, {"routes": results, "errors": errors}
+
+    def build(self) -> tuple[bool, dict] | None:
+        if not self.build_command:
+            return None
+        proc = subprocess.run(self.build_command, shell=True, cwd=self.project, capture_output=True, text=True, timeout=1800, check=False)
+        tail = (proc.stdout + proc.stderr)[-2000:]
+        return proc.returncode == 0, {"command": self.build_command, "exitCode": proc.returncode, "outputTail": tail, "errors": [] if proc.returncode == 0 else [f"build exited {proc.returncode}"]}
+
+    def check(self, step: str) -> tuple[bool, dict] | None:
+        if step in INSPECT_STEPS: return self.inspect(step)
+        if step == "declare-content-source": return self.declare_content_source()
+        if step == "capture-before": return self.snapshot("before") if self.stage == "before" else None
+        if step == "capture-after": return self.snapshot("after") if self.stage == "after" else None
+        if step == "assert-unchanged-rest": return self.unchanged_rest() if self.stage == "after" else None
+        if step == "capture-responsive-screenshots": return self.screenshots()
+        if step == "accessibility-check": return self.accessibility()
+        if step == "route-validation": return self.route_validation()
+        if step == "build-check": return self.build()
+        return None
+
+    def run(self, recheck: bool) -> dict:
+        steps = self.job.get("steps") or []
+        report_steps = []
+        for step in steps:
+            name = str(step.get("name"))
+            if step.get("status") == "done" and not recheck:
+                report_steps.append({"step": name, "status": "done", "evidence": step.get("evidence"), "action": "kept"})
+                continue
+            if name in MANUAL_STEPS:
+                report_steps.append({"step": name, "status": step.get("status", "pending"), "action": "requires implementer or reviewer evidence: maggie design step " + self.job_id + f" --step {name} --evidence FILE"})
+                continue
+            outcome = self.check(name)
+            if outcome is None:
+                reason = "not part of this stage" if name in {"capture-before", "capture-after", "assert-unchanged-rest"} else ("pass --build-command to run the host build" if name == "build-check" else "no automated check for this step")
+                report_steps.append({"step": name, "status": step.get("status", "pending"), "action": reason})
+                continue
+            passed, payload = outcome
+            payload = {"schemaVersion": "maggie-design-step-evidence.v1", "jobId": self.job_id, "step": name, "passed": passed, "checkedAt": now(), **payload}
+            path = self.write(name, payload)
+            if passed:
+                step.update({"status": "done", "evidence": str(path), "completedAt": now(), "verifiedBy": "maggie design verify"})
+                self.job.setdefault("history", []).append({"event": "step-completed", "step": name, "evidence": str(path), "at": now(), "verifiedBy": "maggie design verify"})
+            else:
+                step["lastCheck"] = {"passed": False, "evidence": str(path), "at": now()}
+            report_steps.append({"step": name, "status": step.get("status", "pending"), "action": "verified" if passed else "failed", "evidence": str(path), "errors": payload.get("errors", [])[:10]})
+        self.job["phase"] = "done" if steps and all(item.get("status") == "done" for item in steps) else "ready"
+        self.job["updated_at"] = now()
+        self.job_path.write_text(json.dumps(self.job, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        failed = [item["step"] for item in report_steps if item.get("action") == "failed"]
+        pending = [item["step"] for item in report_steps if item.get("status") != "done"]
+        return {"schemaVersion": SCHEMA, "jobId": self.job_id, "mode": self.job.get("mode"), "stage": self.stage, "routes": self.routes, "phase": self.job["phase"], "passed": not failed, "failedSteps": failed, "pendingSteps": pending, "steps": report_steps, "evidenceDir": str(self.evidence_dir), "mutation": "job step records only"}
+
+
+def verify(project: Path, job_id: str, base_url: str | None, dist: Path | None, stage: str, build_command: str | None, recheck: bool, budget_ms: int, require_browser: bool) -> dict:
+    if bool(base_url) == bool(dist):
+        raise ValueError("exactly one of --base-url or --dist is required")
+    if base_url and urlsplit(base_url).scheme not in {"http", "https"}:
+        raise ValueError("--base-url must be http(s)")
+    try:
+        chrome: str | None = find_chrome()
+    except RuntimeError:
+        if require_browser:
+            raise
+        chrome = None
+    with _ProbeServer("", base_url=base_url, dist=dist) as server:
+        verifier = Verifier(project.resolve(), job_id, server, chrome, stage, build_command, budget_ms)
+        return verifier.run(recheck)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design verify", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("job_id")
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--base-url", help="running host origin (GET-only)")
+    parser.add_argument("--dist", type=Path, help="static build directory")
+    parser.add_argument("--stage", choices=("before", "after"), default="after", help="section jobs: capture before editing, then verify after")
+    parser.add_argument("--build-command", help="explicit host build command for the build-check step")
+    parser.add_argument("--recheck", action="store_true", help="re-run steps that are already done")
+    parser.add_argument("--budget-ms", type=int, default=6000)
+    parser.add_argument("--require-browser", action="store_true", help="fail instead of falling back to static HTML when Chrome is unavailable")
+    args = parser.parse_args(argv)
+    try:
+        report = verify(args.project, args.job_id, args.base_url, args.dist, args.stage, args.build_command, args.recheck, args.budget_ms, args.require_browser)
+    except (OSError, ValueError, RuntimeError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie-design verify: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())